fui-material 2.2.13 → 2.2.15

package/dist/types/function-elements/fBankRound/fBankRound.d.ts

@@ -1,22 +1,40 @@
 /**
- * Выполняет российское банковское округление (ГОСТ Р 8.736-2011).
+ * Выполняет банковское округление числа (по ГОСТ Р 8.736-2011) с учётом практических особенностей,
+ * используемых в финансовых калькуляторах.
  *
- * Правило:
- *  - Если дробная часть < 0.5 → округляется вниз
- *  - Если дробная часть > 0.5 → округляется вверх
- *  - Если дробная часть = 0.5 → округляется к ближайшему чётному числу
+ * ### Математика банковского округления
  *
- * Функция поддерживает числа с любым количеством знаков после запятой.
+ * Банковское округление (англ. *bankers' rounding*, *round-to-even*) — метод, минимизирующий накопление ошибок
+ * при многократных операциях. Отличается от стандартного округления только при **ровно 5**:
  *
- * @param value - Число (или строка), которое нужно округлить.
- * @param decimals - Количество знаков после запятой, до которых округлять.
- * @returns Округлённое число.
+ * | Условие | Действие |
+ * |--------|---------|
+ * | `roundingDigit > 5` | Округление вверх |
+ * | `roundingDigit < 5` | Округление вниз |
+ * | `roundingDigit = 5` и **есть ненулевые цифры после** (`hasTail`) | Округление вверх |
+ * | `roundingDigit = 5` и **все нули после** | Округляем так, чтобы **последняя сохраняемая цифра была чётной** |
+ *
+ * **НО:** в банковских системах и калькуляторах **для отрицательных чисел** при `=5` — **всегда вверх**,
+ * чтобы избежать "потери копейки" в пользу клиента.
+ *
+ * ---
+ *
+ * ### Примеры
+ * - `1.2345` → `1.234` (до 3 знаков): `lastKept = 4` (чёт) → вниз
+ * - `1.2355` → `1.236` (до 3 знаков): `lastKept = 5` (нечёт) → вверх → `6` (чёт)
+ * - `-1.225` → `-1.23` (до 2 знаков): отрицательное + `=5` → вверх
+ * - `2.5` → `2` (до 0): `lastKept = 2` (чёт) → вниз
+ * - `-2.5` → `-3` (до 0): отрицательное + `=5` → вверх
+ *
+ * @param value - Число или строка, которую нужно округлить.
+ * @param decimals - Количество знаков после запятой (по умолчанию 2).
+ * @returns Округлённое число или `NaN`, если вход некорректен.
  *
  * @example
- * fBankRound(1.225, 2) // → 1.22
- * fBankRound(1.235, 2) // → 1.24
- * fBankRound(2.5, 0)   // → 2
- * fBankRound(3.5, 0)   // → 4
+ * fBankRound(1.225, 2);     // → 1.22
+ * fBankRound(-1.225, 2);    // → -1.23
+ * fBankRound(2.5, 0);       // → 2
+ * fBankRound(-2.5, 0);      // → -3
  */
 declare function fBankRound(value: number | string, decimals?: number): number;
 export default fBankRound;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fui-material",
-  "version": "2.2.13",
+  "version": "2.2.15",
   "type": "module",
   "publishConfig": {
     "access": "public",