@omnisass/library 0.2.0

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

@@ -0,0 +1,172 @@
+/// Денормализует число из единичного интервала [0, 1] в
+/// исходный диапазон.
+///
+/// Функция выполняет обратное линейное преобразование числа
+/// из нормализованного диапазона `[0, 1]` обратно в исходный
+/// диапазон `[$min, $max]`. Это операция, обратная функции
+/// `number-normalize()`, и восстанавливает исходное значение
+/// после нормализации.
+///
+/// Математическая формула:
+/// - `denormalized = value * (max - min) + min`
+///
+/// Свойства результата:
+/// - Если `value = 0` → возвращает `min`
+/// - Если `value = 1` → возвращает `max`
+/// - Если `value = 0.5` → возвращает значение посередине
+/// 	между `min` и `max`
+/// - Если `value` находится вне [0, 1] → выполняет
+/// 	экстраполяцию
+///
+/// Важные особенности функции:
+/// - Выполняет обратное преобразование к `number-normalize()`
+/// - Восстанавливает исходные единицы измерения, если они были
+/// - Работает с любыми числовыми значениями
+/// - Поддерживает экстраполяцию для значений вне [0, 1]
+/// - Сохраняет линейное соответствие между диапазонами
+/// - Основная операция для интерполяции и ремаппинга значений
+///
+/// > Эта функция является точной обратной операцией к
+/// > `number-normalize()`. Для любого значения `x` в диапазоне
+/// > `[$min, $max]` выполняется тождество:
+/// > `number-denormalize(number-normalize(x, $min, $max), $min, $max) == x`.
+/// > Функция также поддерживает экстраполяцию для значений
+/// > вне диапазона [0, 1], что полезно для выхода за пределы
+/// > исходного диапазона или для работы с выбросами.
+/// ---
+/// @name number-denormalize
+/// @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://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-denormalize(0.5, 0, 100);    // 50
+/// 	@debug number-denormalize(0.25, 0, 100);   // 25
+/// 	@debug number-denormalize(0.75, 0, 100);   // 75
+/// 	@debug number-denormalize(0, 0, 100);      // 0
+/// 	@debug number-denormalize(1, 0, 100);      // 100
+/// @example scss - Обратное преобразование (round-trip)
+/// 	// Доказательство корректности: денормализация нормализованного значения
+/// 	// должна давать исходное значение
+/// 	$original: 42;
+/// 	$normalized: math.div($original - 0, 100 - 0); // 0.42
+/// 	$denormalized: number-denormalize($normalized, 0, 100); // 42
+/// 	@debug $original == $denormalized; // true
+///
+/// 	// С нестандартным диапазоном
+/// 	$original: 35;
+/// 	$normalized: math.div($original - 10, 50 - 10); // 0.625
+/// 	$denormalized: number-denormalize($normalized, 10, 50); // 35
+/// 	@debug $original == $denormalized; // true
+/// @example scss - Нестандартные диапазоны
+/// 	@debug number-denormalize(0.5, 10, 50);    // 30
+/// 	@debug number-denormalize(0.25, 10, 50);   // 20
+/// 	@debug number-denormalize(0.75, 10, 50);   // 40
+/// 	@debug number-denormalize(0, 10, 50);      // 10
+/// 	@debug number-denormalize(1, 10, 50);      // 50
+/// @example scss - Отрицательные диапазоны
+/// 	@debug number-denormalize(0.5, -100, 0);   // -50
+/// 	@debug number-denormalize(0.25, -100, 0);  // -75
+/// 	@debug number-denormalize(0.75, -100, 0);  // -25
+/// 	@debug number-denormalize(0, -100, 0);     // -100
+/// 	@debug number-denormalize(1, -100, 0);     // 0
+/// @example scss - Смешанные положительные/отрицательные
+/// 	@debug number-denormalize(0.5, -50, 50);   // 0
+/// 	@debug number-denormalize(0.25, -50, 50);  // -25
+/// 	@debug number-denormalize(0.75, -50, 50);  // 25
+/// 	@debug number-denormalize(0, -50, 50);     // -50
+/// 	@debug number-denormalize(1, -50, 50);     // 50
+/// @example scss - Дробные нормализованные значения
+/// 	@debug number-denormalize(0.314, 0, 10);   // 3.14
+/// 	@debug number-denormalize(0.1618, 0, 10);  // 1.6179999999999999
+/// 	@debug number-denormalize(0.8675, 0, 10);  // 8.675
+/// 	@debug number-denormalize(0.12345, 0, 1);  // 0.12345
+/// 	@debug number-denormalize(0.98765, 0, 1);  // 0.98765
+/// @example scss - Маленькие диапазоны
+/// 	@debug number-denormalize(0.5, 1, 2);      // 1.5
+/// 	@debug number-denormalize(0.25, 1, 2);     // 1.25
+/// 	@debug number-denormalize(0.75, 1, 2);     // 1.75
+/// 	@debug number-denormalize(0.1, 1, 2);      // 1.1
+/// 	@debug number-denormalize(0.9, 1, 2);      // 1.9
+/// @example scss - Большие диапазоны
+/// 	@debug number-denormalize(0.5, 0, 10000);  // 5000
+/// 	@debug number-denormalize(0.25, 0, 10000); // 2500
+/// 	@debug number-denormalize(0.75, 0, 10000); // 7500
+/// 	@debug number-denormalize(0.01, 0, 10000); // 100
+/// 	@debug number-denormalize(0.99, 0, 10000); // 9900
+/// @example scss - Экстраполяция (значения вне [0, 1])
+/// 	@debug number-denormalize(-0.1, 0, 100);   // -10
+/// 	@debug number-denormalize(1.1, 0, 100);    // 110.00000000000001
+/// 	@debug number-denormalize(1.5, 0, 100);    // 150
+/// 	@debug number-denormalize(-0.5, 0, 100);   // -50
+/// 	@debug number-denormalize(2.0, 0, 100);    // 200
+/// @example scss - Восстановление единиц измерения
+/// 	@debug number-denormalize(0.25, 0px, 100px); // 25px
+/// 	@debug number-denormalize(0.5, 0px, 100px);  // 50px
+/// 	@debug number-denormalize(0.75, 0px, 100px); // 75px
+/// 	@debug number-denormalize(0, 0px, 100px);    // 0px
+/// 	@debug number-denormalize(1, 0px, 100px);    // 100px
+/// @example scss - Разные единицы измерения
+/// 	@debug number-denormalize(0.5, 0rem, 2rem);  // 1rem
+/// 	@debug number-denormalize(0.75, 0rem, 2rem); // 1.5rem
+/// 	@debug number-denormalize(0.25, 0rem, 2rem); // 0.5rem
+/// 	@debug number-denormalize(0, 0rem, 2rem);    // 0rem
+/// 	@debug number-denormalize(1, 0rem, 2rem);    // 2rem
+/// @example scss - Процентные диапазоны
+/// 	@debug number-denormalize(0.5, 0%, 100%);   // 50%
+/// 	@debug number-denormalize(0.25, 0%, 100%);  // 25%
+/// 	@debug number-denormalize(0.75, 0%, 100%);  // 75%
+/// 	@debug number-denormalize(0, 0%, 100%);     // 0%
+/// 	@debug number-denormalize(1, 0%, 100%);     // 100%
+/// @example scss - Нецелочисленные границы
+/// 	@debug number-denormalize(0.5, 1.5, 5.5);   // 3.5
+/// 	@debug number-denormalize(0.25, 1.5, 5.5);  // 2.5
+/// 	@debug number-denormalize(0.75, 1.5, 5.5);  // 4.5
+/// 	@debug number-denormalize(0, 1.5, 5.5);     // 1.5
+/// 	@debug number-denormalize(1, 1.5, 5.5);     // 5.5
+/// @example scss - Очень малые нормализованные значения
+/// 	@debug number-denormalize(0.5, 0, 1);       // 0.5
+/// 	@debug number-denormalize(0.25, 0, 1);      // 0.25
+/// 	@debug number-denormalize(0.75, 0, 1);      // 0.75
+/// 	@debug number-denormalize(0.001, 0, 1);     // 0.001
+/// 	@debug number-denormalize(0.999, 0, 1);     // 0.999
+/// @example scss - Симметричные диапазоны
+/// 	@debug number-denormalize(0.5, -1, 1);      // 0
+/// 	@debug number-denormalize(0.75, -1, 1);     // 0.5
+/// 	@debug number-denormalize(0.25, -1, 1);     // -0.5
+/// 	@debug number-denormalize(1, -1, 1);        // 1
+/// 	@debug number-denormalize(0, -1, 1);        // -1
+/// @example scss - Инверсная проверка
+/// 	// Для любого x в [min, max] должно выполняться:
+/// 	// number-denormalize(number-normalize(x, min, max), min, max) == x
+/// 	@debug number-denormalize(number-normalize(30, 10, 50), 10, 50); // 30
+/// 	@debug number-denormalize(number-normalize(-25, -50, 50), -50, 50); // -25
+/// 	@debug number-denormalize(number-normalize(7.5, 0, 10), 0, 10); // 7.5
+/// 	@debug number-denormalize(number-normalize(75%, 0%, 100%), 0%, 100%); // 75%
+/// 	@debug number-denormalize(number-normalize(1.75, 1, 2), 1, 2); // 1.75
+/// @param {Number} $value - Нормализованное значение в
+/// 	диапазоне [0, 1]. Обычно полученное с помощью
+/// 	`number-normalize()`. Может быть любым числом, включая
+/// 	значения вне [0, 1] для экстраполяции.
+/// @param {Number} $min - Нижняя граница целевого диапазона.
+/// 	Значение, соответствующее `0` в нормализованном диапазоне.
+/// @param {Number} $max - Верхняя граница целевого диапазона.
+/// 	Значение, соответствующее `1` в нормализованном диапазоне.
+/// @return {Number} - Денормализованное значение в целевом
+/// 	диапазоне. Восстанавливает исходные единицы измерения
+/// 	из `$min` и `$max`. Для `$value` в [0, 1] результат
+/// 	будет в диапазоне `[$min, $max]`. Для значений вне [0, 1]
+/// 	выполняет линейную экстраполяцию.
+/// @throws Не выбрасывает ошибок, безопасно обрабатывает все
+/// 	числовые значения. Формула математически корректна для
+/// 	любых числовых аргументов.
+@function number-denormalize($value, $min, $max) {
+	@return $value * ($max - $min) + $min;
+}

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

@@ -0,0 +1,235 @@
+@use 'sass:list';
+
+/// Генерирует последовательность чисел Фибоначчи.
+///
+/// Функция `number-fibonacci()` создает упорядоченный
+/// список первых `$n` чисел последовательности Фибоначчи,
+/// начиная с 1. Последовательность Фибоначчи — это ряд
+/// чисел, где каждое последующее число является суммой двух
+/// предыдущих: 1, 1, 2, 3, 5, 8, 13, 21, ...
+///
+/// Эта функция реализует классическую итеративную версию
+/// генерации чисел Фибоначчи с линейной сложностью O(n).
+/// Результат всегда начинается с 1 и включает ровно `$n`
+/// первых чисел последовательности.
+///
+/// Числа Фибоначчи широко используются в дизайне, типографике,
+/// создании гармоничных пропорций и масштабируемых систем:
+/// - Золотое сечение (φ ≈ 1.618)
+/// - Модульные сетки и композиция
+/// - Шкалы размеров и отступов
+/// - Анимации с естественным ускорением
+///
+/// > Числа Фибоначчи растут экспоненциально: `F(n) ≈ φ^n / √5`.
+/// > Уже на 50-м числе значение превышает 12 миллионов.
+/// ---
+/// @name number-fibonacci
+/// @group utilities-helpers
+/// @since 2025.12.28
+/// @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://ru.wikipedia.org/wiki/Числа_Фибоначчи См. также: Википедия - Числа Фибоначчи
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout См. также: MDN - CSS Grid Layout
+/// @link https://www.smashingmagazine.com/2008/05/applying-mathematics-to-web-design/ См. также: Smashing Magazine - Математика в веб-дизайне
+/// @link https://www.w3.org/TR/css-values-4/#numeric-types См. также: W3C - Числовые типы CSS
+/// @example scss - Генерация базовой последовательности Фибоначчи
+/// 	@use 'sass:list';
+///
+/// 	$fibonacci: number-fibonacci(8);
+/// 	// Возвращает: (1, 1, 2, 3, 5, 8, 13, 21)
+///
+/// 	@each $number in $fibonacci {
+/// 		.scale-#{$number} {
+/// 			font-size: #{$number * 4}px;
+/// 			line-height: 1.2;
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	.scale-1 {
+/// 		font-size: 4px;
+/// 		line-height: 1.2;
+/// 	}
+/// 	.scale-1 {
+/// 		font-size: 4px;
+/// 		line-height: 1.2;
+/// 	}
+/// 	.scale-2 {
+/// 		font-size: 8px;
+/// 		line-height: 1.2;
+/// 	}
+/// 	.scale-3 {
+/// 		font-size: 12px;
+/// 		line-height: 1.2;
+/// 	}
+/// 	.scale-5 {
+/// 		font-size: 20px;
+/// 		line-height: 1.2;
+/// 	}
+/// 	.scale-8 {
+/// 		font-size: 32px;
+/// 		line-height: 1.2;
+/// 	}
+/// 	.scale-13 {
+/// 		font-size: 52px;
+/// 		line-height: 1.2;
+/// 	}
+/// 	.scale-21 {
+/// 		font-size: 84px;
+/// 		line-height: 1.2;
+/// 	}
+/// @example scss - Создание пропорциональной сетки на основе Фибоначчи
+/// 	@use 'sass:list';
+/// 	@use 'sass:math';
+///
+/// 	$fib-grid: number-fibonacci(6);
+/// 	// Возвращает: (1, 1, 2, 3, 5, 8)
+///
+/// 	.container {
+/// 		display: grid;
+/// 		grid-template-columns: repeat(#{list.length($fib-grid)}, 1fr);
+/// 		gap: 1rem;
+/// 	}
+///
+/// 	@for $i from 1 through list.length($fib-grid) {
+/// 		$fib-value: list.nth($fib-grid, $i);
+/// 		.cell-#{$i} {
+/// 			grid-column: span $fib-value;
+/// 			padding: #{$fib-value * 0.5}rem;
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	.container {
+/// 		display: grid;
+/// 		grid-template-columns: repeat(6, 1fr);
+/// 		gap: 1rem;
+/// 	}
+/// 	.cell-1 {
+/// 		grid-column: span 1;
+/// 		padding: 0.5rem;
+/// 	}
+/// 	.cell-2 {
+/// 		grid-column: span 1;
+/// 		padding: 0.5rem;
+/// 	}
+/// 	.cell-3 {
+/// 		grid-column: span 2;
+/// 		padding: 1rem;
+/// 	}
+/// 	.cell-4 {
+/// 		grid-column: span 3;
+/// 		padding: 1.5rem;
+/// 	}
+/// 	.cell-5 {
+/// 		grid-column: span 5;
+/// 		padding: 2.5rem;
+/// 	}
+/// 	.cell-6 {
+/// 		grid-column: span 8;
+/// 		padding: 4rem;
+/// 	}
+/// @example scss - Генерация гармоничных отступов по Фибоначчи
+/// 	@use 'sass:list';
+///
+/// 	:root {
+/// 		$fibonacci-spacing: number-fibonacci(7);
+/// 		// Возвращает: (1, 1, 2, 3, 5, 8, 13)
+///
+/// 		@for $i from 1 through list.length($fibonacci-spacing) {
+/// 			$value: list.nth($fibonacci-spacing, $i);
+/// 			--space-#{$i}: #{$value * 0.25}rem;
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	:root {
+/// 		--space-1: 0.25rem;
+/// 		--space-2: 0.25rem;
+/// 		--space-3: 0.5rem;
+/// 		--space-4: 0.75rem;
+/// 		--space-5: 1.25rem;
+/// 		--space-6: 2rem;
+/// 		--space-7: 3.25rem;
+/// 	}
+/// @example scss - Анимация с естественным ускорением по Фибоначчи
+/// 	@use 'sass:list';
+///
+/// 	$timing-steps: number-fibonacci(6);
+/// 	// Возвращает: (1, 1, 2, 3, 5, 8)
+///
+/// 	@keyframes natural-slide {
+/// 		@for $i from 1 through list.length($timing-steps) {
+/// 			$step: $i - 1;
+/// 			$fib-value: list.nth($timing-steps, $i);
+/// 			$percentage: math.div($step * 100, list.length($timing-steps) - 1);
+///
+/// 			#{$percentage}% {
+/// 				transform: translateX(#{$fib-value * 10}px);
+/// 				animation-timing-function: cubic-bezier(0.25, 0.1, 0.25, 1);
+/// 			}
+/// 		}
+/// 	}
+///
+/// 	.element {
+/// 		animation: natural-slide 2s infinite;
+/// 	}
+/// @example css - Результат
+/// 	@keyframes natural-slide {
+/// 		0% {
+/// 			transform: translateX(10px);
+/// 			animation-timing-function: cubic-bezier(0.25, 0.1, 0.25, 1);
+/// 		}
+/// 		20% {
+/// 			transform: translateX(10px);
+/// 			animation-timing-function: cubic-bezier(0.25, 0.1, 0.25, 1);
+/// 		}
+/// 		40% {
+/// 			transform: translateX(20px);
+/// 			animation-timing-function: cubic-bezier(0.25, 0.1, 0.25, 1);
+/// 		}
+/// 		60% {
+/// 			transform: translateX(30px);
+/// 			animation-timing-function: cubic-bezier(0.25, 0.1, 0.25, 1);
+/// 		}
+/// 		80% {
+/// 			transform: translateX(50px);
+/// 			animation-timing-function: cubic-bezier(0.25, 0.1, 0.25, 1);
+/// 		}
+/// 		100% {
+/// 			transform: translateX(80px);
+/// 			animation-timing-function: cubic-bezier(0.25, 0.1, 0.25, 1);
+/// 		}
+/// 	}
+/// 	.element {
+/// 		animation: natural-slide 2s infinite;
+/// 	}
+/// @param {Number} $n - Количество чисел Фибоначчи для генерации.
+/// 	Определяет длину возвращаемой последовательности.
+/// 	Должно быть положительным целым числом больше 0.
+/// 	Для больших значений (n > 40) может вызвать переполнение
+/// 	из-за экспоненциального роста чисел.
+/// @return {List} - Упорядоченный список (list) чисел Фибоначчи, где:
+/// - Количество элементов: ровно `$n`
+/// - Первый элемент: всегда 1
+/// - Второй элемент: всегда 1 (если `$n > 1`)
+/// - Каждый последующий элемент: сумма двух предыдущих
+/// - Все элементы: целые положительные числа
+@function number-fibonacci($n) {
+	$-result: ();
+	$-a: 0;
+	$-b: 1;
+
+	@for $i from 1 through $n {
+
+		$-result: list.append($-result, $-b);
+		$-temp: $-a + $-b;
+		$-a: $-b;
+		$-b: $-temp;
+
+	}
+
+	@return $-result;
+
+}

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

@@ -0,0 +1,114 @@
+@use 'sass:math';
+
+/// Округляет число вниз до ближайшего кратного значения.
+///
+/// Функция выполняет округление числа вниз (в сторону
+/// отрицательной бесконечности) до ближайшего значения,
+/// кратного указанному числу.
+///
+/// Используется для выравнивания значений по сетке или
+/// заданному шагу, гарантируя, что результат не превысит
+/// исходное значение.
+///
+/// Важные особенности функции:
+/// - Всегда округляет вниз (в сторону уменьшения)
+/// - Работает с положительными и отрицательными числами
+/// - Сохраняет единицы измерения исходного числа
+/// - Использует `math.floor()` для округления вниз
+/// - Поддерживает дробные значения для `$nearest`
+/// - Использует математически корректное деление через
+/// 	`math.div()`
+/// ---
+/// @name number-floor-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#floor См. также: Официальная документация Sass - Функция math.floor()
+/// @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/floor MDN Web Docs - Math.floor()
+/// @link https://en.wikipedia.org/wiki/Floor_and_ceiling_functions См. также: Википедия - Функции пол и потолок
+/// @link https://mathworld.wolfram.com/FloorFunction.html См. также: Wolfram MathWorld - Функция пол
+/// @link https://www.britannica.com/science/floor-function См. также: Britannica - Функция пол в математике
+/// @link https://www.khanacademy.org/math/algebra/x2f8bb11595b61c86:functions/x2f8bb11595b61c86:graphs-of-piecewise-linear-functions/v/floor-function См. также: Khan Academy - Функция пол
+/// @link https://www.mathsisfun.com/sets/function-floor-ceiling.html См. также: Maths is Fun - Функции пол и потолок
+/// @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-floor-to(13, 5);        // 10
+/// 	@debug number-floor-to(17, 10);       // 10
+/// 	@debug number-floor-to(23, 4);        // 20
+/// 	@debug number-floor-to(100, 50);      // 100
+/// 	@debug number-floor-to(101, 50);      // 100
+/// @example scss - Округление дробных чисел
+/// 	@debug number-floor-to(12.3, 5);      // 10
+/// 	@debug number-floor-to(3.14, 1);      // 3
+/// 	@debug number-floor-to(7.89, 2.5);    // 7.5
+/// 	@debug number-floor-to(0.333, 0.25);  // 0.25
+/// @example scss - Округление отрицательных чисел
+/// 	@debug number-floor-to(-13, 5);       // -15
+/// 	@debug number-floor-to(-17, 10);      // -20
+/// 	@debug number-floor-to(-23, 4);       // -24
+/// 	@debug number-floor-to(-3.5, 1);      // -4
+/// @example scss - Округление чисел с единицами измерения
+/// 	@debug number-floor-to(13px, 5px);    // 10px
+/// 	@debug number-floor-to(1.7rem, 0.5rem); // 1.5rem
+/// 	@debug number-floor-to(45%, 10%);     // 40%
+/// 	@debug number-floor-to(120deg, 90deg); // 90deg
+/// @example scss - Практическое использование для гарантированного размера
+/// 	$available-width: 287px;
+/// 	$column-size: 70px;
+/// 	$max-columns: math.div(number-floor-to($available-width, $column-size), $column-size);
+/// 	// $max-columns: 4 (280px / 70px)
+/// 	.grid {
+/// 		grid-template-columns: repeat($max-columns, 1fr);
+/// 	}
+/// @example css - Результат
+/// 	.grid {
+/// 		grid-template-columns: repeat(4, 1fr);
+/// 	}
+/// @example scss - Практическое использование для бюджета
+/// 	$budget: 1450;
+/// 	$item-price: 300;
+/// 	$max-items: math.div(number-floor-to($budget, $item-price), $item-price);
+/// 	// $max-items: 4 (1200 / 300)
+/// 	// Можно купить максимум 4 предмета, не превышая бюджет
+/// @example scss - Практическое использование для времени
+/// 	$total-seconds: 3675;
+/// 	$minute: 60;
+/// 	$full-minutes: number-floor-to($total-seconds, $minute);
+/// 	// $full-minutes: 3660 секунд (61 минута)
+/// 	.timer {
+/// 		content: "#{math.div($full-minutes, $minute)} мин";
+/// 	}
+/// @example css - Результат
+/// 	.timer {
+/// 		content: "61 мин";
+/// 	}
+/// @example scss - Математическое применение для дискретизации
+/// 	// Дискретизация непрерывного значения
+/// 	$continuous-value: 7.8;
+/// 	$quantization-step: 0.5;
+/// 	$discrete-value: number-floor-to($continuous-value, $quantization-step);
+/// 	// $discrete-value: 7.5
+/// @param {Number} $value - Число для округления. Может быть
+/// 	любым числом: положительным, отрицательным, целым,
+/// 	дробным, с единицами измерения или без них.
+/// @param {Number} $nearest - Кратное значение, до которого
+/// 	нужно округлить. Определяет шаг округления. Может быть
+/// 	дробным числом. Рекомендуется использовать те же единицы
+/// 	измерения, что и у `$value`.
+/// @return {Number} - Число, округленное вниз до ближайшего
+/// 	значения, кратного `$nearest`. Сохраняет единицы
+/// 	измерения исходного числа `$value`.
+/// @throws {Error} - Может выбросить ошибку если `$value` или
+/// 	`$nearest` не являются числами, или если происходит
+/// 	деление на ноль.
+@function number-floor-to($value, $nearest) {
+	@return math.floor(math.div($value, $nearest)) * $nearest;
+}

package/modules/utilities/helpers/number/_number-format-with-separator.scss

@@ -0,0 +1,122 @@
+@use 'sass:math';
+@use 'sass:meta';
+@use 'sass:string';
+
+/// Форматирует число, добавляя разделители тысяч для улучшения
+/// читаемости больших чисел.
+///
+/// Функция преобразует число в строку с разделителями тысяч,
+/// используя указанный разделитель. Разделитель вставляется
+/// между каждой группой из трех цифр, начиная справа (от
+/// десятичной точки). Функция работает с целыми числами и
+/// сохраняет знак отрицательных чисел.
+///
+/// Важные особенности функции:
+/// - Работает только с целыми числами
+/// - Поддерживает отрицательные числа
+/// - Использует математический модуль `math.abs()` для
+/// 	обработки знака
+/// - Использует строковые функции `meta.inspect()`,
+/// 	`string.length()` и `string.slice()`
+/// - Разделитель вставляется между каждой группой из трех
+/// 	цифр справа налево
+/// - Использует локальные переменные с префиксом `$-` для
+/// 	избежания конфликтов
+/// ---
+/// @name number-format-with-separator
+/// @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#abs См. также: Официальная документация Sass - Функция math.abs()
+/// @link https://sass-lang.com/documentation/modules/string См. также: Официальная документация Sass - Строковые функции
+/// @link https://sass-lang.com/documentation/breaking-changes/css-parser См. также: Официальная документация Sass - Функция inspect()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString MDN Web Docs - Number.toLocaleString()
+/// @link https://css-tricks.com/snippets/sass/number-formatting-mixin/ CSS-Tricks - Миксин форматирования чисел
+/// @example scss - Форматирование с разделителем по умолчанию (запятая)
+/// 	@debug number-format-with-separator(1000);      // "1,000"
+/// 	@debug number-format-with-separator(1000000);   // "1,000,000"
+/// 	@debug number-format-with-separator(123456789); // "123,456,789"
+/// 	@debug number-format-with-separator(42);        // "42"
+/// 	@debug number-format-with-separator(999);       // "999"
+/// @example scss - Форматирование с различными разделителями
+/// 	@debug number-format-with-separator(1000, " "); // "1 000"
+/// 	@debug number-format-with-separator(1000000, "."); // "1.000.000"
+/// 	@debug number-format-with-separator(123456789, "'"); // "123'456'789"
+/// 	@debug number-format-with-separator(987654, " "); // "987 654" (неразрывный пробел)
+/// @example scss - Форматирование отрицательных чисел
+/// 	@debug number-format-with-separator(-1000);     // "-1,000"
+/// 	@debug number-format-with-separator(-1234567);  // "-1,234,567"
+/// 	@debug number-format-with-separator(-42);       // "-42"
+/// @example scss - Практическое использование для цен и статистики
+/// 	$population: 7812345;
+/// 	$formatted-population: number-format-with-separator($population);
+/// 	// $formatted-population: "7,812,345"
+/// 	.city-stats::before {
+/// 		content: "Население: #{$formatted-population} человек";
+/// 	}
+/// @example css - Результат
+/// 	.city-stats::before {
+/// 		content: "Население: 7,812,345 человек";
+/// 	}
+/// @example scss - Практическое использование с различными разделителями
+/// 	$revenue: 1500000;
+/// 	$formatted-revenue-eu: number-format-with-separator($revenue, " ");
+/// 	$formatted-revenue-us: number-format-with-separator($revenue, ",");
+/// 	// $formatted-revenue-eu: "1 500 000"
+/// 	// $formatted-revenue-us: "1,500,000"
+/// 	.revenue-eu::after {
+/// 		content: "#{$formatted-revenue-eu} €";
+/// 	}
+/// 	.revenue-us::after {
+/// 		content: "$#{$formatted-revenue-us}";
+/// 	}
+/// @example css - Результат
+/// 	.revenue-eu::after {
+/// 		content: "1 500 000 €";
+/// 	}
+/// 	.revenue-us::after {
+/// 		content: "$1,500,000";
+/// 	}
+/// @param {Number} $value - Число для форматирования. Дробная
+/// 	часть (если есть) будет игнорироваться, так как функция
+/// 	работает только с целой частью числа. Поддерживает
+/// 	отрицательные числа.
+/// @param {String} $separator [","] - Строка-разделитель,
+/// 	которая будет вставляться между группами из трех цифр.
+/// 	По умолчанию используется запятая (","). Может быть
+/// 	любым строковым символом или последовательностью символов.
+/// @return {String} - Отформатированная строка с разделителями
+/// 	тысяч. Отрицательные числа начинаются с минуса, дробная
+/// 	часть исходного числа игнорируется.
+/// @throws {Error} - Может выбросить ошибку если `$value`
+/// 	не является числом или если `$separator` не является строкой.
+@function number-format-with-separator($value, $separator: ",") {
+
+	$-result: "";
+	$-str: meta.inspect(math.abs($value));
+	$-length: string.length($-str);
+	$-counter: 0;
+
+	@for $i from $-length through 1 {
+
+		$char: string.slice($-str, $i, $i);
+		$-result: $char + $-result;
+		$-counter: $-counter + 1;
+
+		@if $-counter == 3 and $i > 1 {
+			$-result: $separator + $-result;
+			$-counter: 0;
+		}
+
+	}
+
+	@if $value < 0 {
+		$-result: "-" + $-result;
+	}
+
+	@return $-result;
+
+}