@ryuzaki13/react-foundation-ui 1.8.6 → 1.8.8

package/storybook-static/assets/README-Q-znYcgF.js

@@ -0,0 +1,338 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-C5-IVaAZ.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-Dx5UE11l.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/API/Formatters/Number`}),`
+`,(0,c.jsx)(t.h1,{id:`числовые-форматтеры`,children:`Числовые форматтеры`}),`
+`,(0,c.jsx)(t.p,{children:`Модуль форматирует числа для интерфейса, читает распространённые SAP-подобные числовые строки и управляет реестром именованных presets.`}),`
+`,(0,c.jsx)(t.p,{children:`Все API доступны через один публичный entrypoint:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	formatNumber,
+	formatNumberAsDecimal2,
+	formatNumberAsInteger,
+	isZeroValue,
+	parseNumber,
+	toFiniteNumber
+} from "@ryuzaki13/react-foundation-lib/formatters";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Импорта `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/formatters/number`}),` нет.`]}),`
+`,(0,c.jsx)(t.h2,{id:`быстрый-старт`,children:`Быстрый старт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	formatNumberAsDecimal2,
+	formatNumberAsInteger,
+	formatNumberAsPercent,
+	toFiniteNumber
+} from "@ryuzaki13/react-foundation-lib/formatters";
+
+formatNumberAsInteger(1234.6); // "1\xA0235"
+formatNumberAsDecimal2(1234.5); // "1\xA0234,50"
+formatNumberAsPercent(12.345); // "12,35"
+
+toFiniteNumber("1 234,50"); // 1234.5
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Пробел между группами в результате обычно неразрывный (`,(0,c.jsx)(t.code,{children:`U+00A0`}),` или `,(0,c.jsx)(t.code,{children:`U+202F`}),` в зависимости от JavaScript-среды). Внешне он выглядит как обычный пробел.`]}),`
+`,(0,c.jsx)(t.h2,{id:`два-разных-пути-обработки`,children:`Два разных пути обработки`}),`
+`,(0,c.jsx)(t.p,{children:`В модуле есть важное разделение:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`внешняя строка SAP/UI ──→ toFiniteNumber / parseNumber ──→ number
+готовое JS-значение ────→ formatNumber ──────────────────→ string для UI
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`formatNumber`}),` не вызывает SAP-like parser. Она использует обычный `,(0,c.jsx)(t.code,{children:`Number(value)`}),`. Поэтому:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumber("1234.5", "decimal-2"); // "1\xA0234,50"
+formatNumber("1 234,5", "decimal-2"); // "0"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Если строка пришла от пользователя или SAP и содержит разделители, сначала парсите её:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const value = toFiniteNumber("1 234,5");
+const text = value === undefined ? "Некорректно" : formatNumber(value, "decimal-2");
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`встроенные-presets`,children:`Встроенные presets`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Имя`}),(0,c.jsx)(t.th,{style:{textAlign:`right`},children:`Дробных знаков`}),(0,c.jsx)(t.th,{children:`Назначение`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`integer`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`0`}),(0,c.jsx)(t.td,{children:`Целое число`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`decimal`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`1`}),(0,c.jsx)(t.td,{children:`Обычное дробное число`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`decimal-2`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`2`}),(0,c.jsx)(t.td,{children:`Два знака после запятой`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`decimal-3`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`3`}),(0,c.jsx)(t.td,{children:`Три знака после запятой`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`currency`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`0`}),(0,c.jsx)(t.td,{children:`Денежное число без символа валюты`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`price`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`0`}),(0,c.jsx)(t.td,{children:`Цена без символа валюты`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`percent`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`2`}),(0,c.jsxs)(t.td,{children:[`Процентное число без автоматического умножения и знака `,(0,c.jsx)(t.code,{children:`%`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`tonnage`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`1`}),(0,c.jsx)(t.td,{children:`Тоннаж`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`compact-currency`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`0`}),(0,c.jsx)(t.td,{children:`Компактное число, усечение`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`compact-currency-round`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`0`}),(0,c.jsx)(t.td,{children:`Компактное число, округление`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`compact-percent`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`до 2`}),(0,c.jsx)(t.td,{children:`Компактный процент, усечение`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`compact-percent-round`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`до 2`}),(0,c.jsx)(t.td,{children:`Компактный процент, округление`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`compact-tonnage`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`до 1`}),(0,c.jsx)(t.td,{children:`Компактный тоннаж, усечение`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`compact-tonnage-round`})}),(0,c.jsx)(t.td,{style:{textAlign:`right`},children:`до 1`}),(0,c.jsx)(t.td,{children:`Компактный тоннаж, округление`})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Имена регистрозависимы и записываются в нижнем регистре:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumber(10, "integer"); // корректно
+// formatNumber(10, "Integer"); // Error: preset не найден
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Константа `,(0,c.jsx)(t.code,{children:`DEFAULT_NUMBER_PRESET_NAMES`}),` позволяет не дублировать строки:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { DEFAULT_NUMBER_PRESET_NAMES, formatNumber } from "@ryuzaki13/react-foundation-lib/formatters";
+
+formatNumber(1234.5, DEFAULT_NUMBER_PRESET_NAMES.decimal2);
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`formatnumbervalue-presetorname`,children:(0,c.jsx)(t.code,{children:`formatNumber(value, presetOrName)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function formatNumber(value: unknown, presetOrName: string | NumberFormatPreset): string;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Функция:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`отдельно превращает пустую/пробельную строку в `,(0,c.jsx)(t.code,{children:`"0"`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`вызывает `,(0,c.jsx)(t.code,{children:`Number(value)`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`для `,(0,c.jsx)(t.code,{children:`NaN`}),` и бесконечности возвращает `,(0,c.jsx)(t.code,{children:`"0"`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`находит preset по имени или использует переданный объект;`}),`
+`,(0,c.jsx)(t.li,{children:`округляет и форматирует число;`}),`
+`,(0,c.jsx)(t.li,{children:`применяет compact-семантику, если она задана.`}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumber(1234.56, "decimal-2"); // "1\xA0234,56"
+formatNumber(1234.56, "integer"); // "1\xA0235"
+formatNumber("", "decimal"); // "0"
+formatNumber("abc", "decimal"); // "0"
+`})}),`
+`,(0,c.jsxs)(t.h3,{id:`неожиданная-javascript-семантика-number`,children:[`Неожиданная JavaScript-семантика `,(0,c.jsx)(t.code,{children:`Number`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Поскольку вход имеет тип `,(0,c.jsx)(t.code,{children:`unknown`}),`, обычное преобразование JavaScript допускает случаи:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumber(null, "integer"); // "0"
+formatNumber(false, "integer"); // "0"
+formatNumber(true, "integer"); // "1"
+formatNumber([], "integer"); // "0"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Не используйте эти преобразования как бизнес-валидацию. Проверяйте внешние данные до форматирования.`}),`
+`,(0,c.jsxs)(t.p,{children:[`Если значение не преобразовалось в конечное число, функция возвращает `,(0,c.jsx)(t.code,{children:`"0"`}),` ещё до поиска preset. Поэтому неизвестный preset для невалидного значения может не выбросить ошибку:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumber("abc", "unknown"); // "0"
+formatNumber(10, "unknown"); // Error
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`округление`,children:`Округление`}),`
+`,(0,c.jsxs)(t.p,{children:[`Обычные presets используют `,(0,c.jsx)(t.code,{children:`Intl.NumberFormat`}),`, то есть округляют до заданного количества знаков:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumber(1.26, "decimal"); // "1,3"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Старое предположение об усечении для обычных presets неверно. Усечение используется по умолчанию только внутри compact-настроек.`}),`
+`,(0,c.jsx)(t.h2,{id:`готовые-wrappers`,children:`Готовые wrappers`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Функция`}),(0,c.jsx)(t.th,{children:`Preset`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatNumberAsInteger`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`integer`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatNumberAsCurrency`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`currency`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatNumberAsDecimal`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`decimal`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatNumberAsDecimal2`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`decimal-2`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatNumberAsDecimal3`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`decimal-3`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatNumberAsPercent`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`percent`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatNumberAsPrice`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`price`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatNumberAsTonnage`})}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`tonnage`})})]})]})]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumberAsDecimal(12); // "12,0"
+formatNumberAsDecimal2(12); // "12,00"
+formatNumberAsDecimal3(12); // "12,000"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`currency`}),`, `,(0,c.jsx)(t.code,{children:`price`}),` и `,(0,c.jsx)(t.code,{children:`percent`}),` не добавляют обозначение единицы. Они задают только числовой вид:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumberAsCurrency(1250); // "1\xA0250", без ₽
+formatNumberAsPercent(12.5); // "12,50", без %
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Если нужен суффикс, добавляйте его на UI-уровне или используйте специализированный модуль единиц измерения.`}),`
+`,(0,c.jsxs)(t.h2,{id:`wrappers-orempty`,children:[`Wrappers `,(0,c.jsx)(t.code,{children:`OrEmpty`})]}),`
+`,(0,c.jsx)(t.p,{children:`Для каждого wrapper существует вариант, который скрывает семантический ноль:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`formatNumberAsIntegerOrEmpty`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`formatNumberAsCurrencyOrEmpty`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`formatNumberAsDecimalOrEmpty`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`formatNumberAsDecimal2OrEmpty`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`formatNumberAsDecimal3OrEmpty`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`formatNumberAsPercentOrEmpty`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`formatNumberAsPriceOrEmpty`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`formatNumberAsTonnageOrEmpty`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumberAsDecimalOrEmpty(0); // ""
+formatNumberAsDecimalOrEmpty("0,00"); // ""
+formatNumberAsDecimalOrEmpty(" "); // "0"
+formatNumberAsDecimalOrEmpty("abc"); // "0"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Последние два результата объясняются тем, что `,(0,c.jsx)(t.code,{children:`isZeroValue`}),` не считает пустой или невалидный ввод числовым нулём, после чего обычный formatter даёт свой fallback `,(0,c.jsx)(t.code,{children:`"0"`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`compact-форматирование`,children:`Compact-форматирование`}),`
+`,(0,c.jsx)(t.p,{children:`Compact presets сокращают большие значения:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`тыс`}),` — тысячи;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`млн`}),` — миллионы;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`млрд`}),` — миллиарды;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`трлн`}),` — триллионы.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`По умолчанию compact включается при абсолютном значении от `,(0,c.jsx)(t.code,{children:`1000`}),`. Знак отрицательного числа сохраняется.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumber(1_500, "compact-tonnage"); // компактное представление с "тыс"
+formatNumber(2_000_000, "compact-currency"); // представление с "млн"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`maxDecimals`}),` не задан, нормализованные значения меньше `,(0,c.jsx)(t.code,{children:`10`}),` получают до одного дробного знака, а значения от `,(0,c.jsx)(t.code,{children:`10`}),` — целое представление.`]}),`
+`,(0,c.jsx)(t.h3,{id:`усечение-и-округление`,children:`Усечение и округление`}),`
+`,(0,c.jsxs)(t.p,{children:[`Presets без `,(0,c.jsx)(t.code,{children:`-round`}),` используют `,(0,c.jsx)(t.code,{children:`roundingMode: "trunc"`}),`. Парные presets с `,(0,c.jsx)(t.code,{children:`-round`}),` используют математическое `,(0,c.jsx)(t.code,{children:`round`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Для положительного числа усечение просто отбрасывает остаток; для отрицательного оно движется к нулю. Это отличается от `,(0,c.jsx)(t.code,{children:`floor`}),`, который движется к минус бесконечности.`]}),`
+`,(0,c.jsx)(t.h3,{id:`собственные-compact-units`,children:`Собственные compact units`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import type { NumberFormatPreset } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const preset: NumberFormatPreset = {
+	name: "custom-compact",
+	decimals: 1,
+	decimalSeparator: ",",
+	grouping: true,
+	groupingSeparator: " ",
+	groupingSize: 3,
+	compact: {
+		minCompactValue: 10_000,
+		maxDecimals: 1,
+		roundingMode: "round",
+		suffixSeparator: " ",
+		units: [
+			{ value: 1_000_000, suffix: "M" },
+			{ value: 1_000, suffix: "K" }
+		]
+	}
+};
+
+formatNumber(1_250_000, preset); // "1,3 M"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Располагайте units от большей к меньшей: выбирается первая единица, чей `,(0,c.jsx)(t.code,{children:`value`}),` не превышает абсолютное число.`]}),`
+`,(0,c.jsx)(t.h2,{id:`чтение-числовых-строк`,children:`Чтение числовых строк`}),`
+`,(0,c.jsx)(t.h3,{id:`tofinitenumbervalue`,children:(0,c.jsx)(t.code,{children:`toFiniteNumber(value)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function toFiniteNumber(value: unknown): number | undefined;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает только конечное число или `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Поддерживаются:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`готовый `,(0,c.jsx)(t.code,{children:`number`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`стандартная числовая строка JavaScript;`}),`
+`,(0,c.jsx)(t.li,{children:`пробел, NBSP, narrow NBSP и апостроф как разделители групп;`}),`
+`,(0,c.jsx)(t.li,{children:`запятая как десятичный разделитель, если в строке нет точки;`}),`
+`,(0,c.jsxs)(t.li,{children:[`формат `,(0,c.jsx)(t.code,{children:`1,234.56`}),`, где запятые считаются группировкой.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`toFiniteNumber(12.5); // 12.5
+toFiniteNumber(" 12.5 "); // 12.5
+toFiniteNumber("1 234,56"); // 1234.56
+toFiniteNumber("1\\u00a0234,56"); // 1234.56
+toFiniteNumber("1'234,56"); // 1234.56
+toFiniteNumber("1,234.56"); // 1234.56
+toFiniteNumber(""); // undefined
+toFiniteNumber("abc"); // undefined
+toFiniteNumber(Infinity); // undefined
+toFiniteNumber(null); // undefined
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Стандартный `,(0,c.jsx)(t.code,{children:`Number(trimmed)`}),` выполняется первым, поэтому поддерживаются и его синтаксисы, включая exponent и шестнадцатеричную строку:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`toFiniteNumber("1e3"); // 1000
+toFiniteNumber("0x10"); // 16
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`важное-ограничение-двух-разделителей`,children:`Важное ограничение двух разделителей`}),`
+`,(0,c.jsx)(t.p,{children:`Если присутствуют и запятая, и точка, все запятые считаются группировкой:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`toFiniteNumber("1,234.56"); // 1234.56
+toFiniteNumber("1.234,56"); // 1.23456, не 1234.56
+`})}),`
+`,(0,c.jsx)(t.p,{children:`То есть европейская запись с точкой-группировкой и запятой-дробью не поддерживается. Нормализуйте такой источник по его явной locale-схеме до вызова.`}),`
+`,(0,c.jsx)(t.h3,{id:`parsenumbervalue`,children:(0,c.jsx)(t.code,{children:`parseNumber(value)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function parseNumber(value: unknown): number;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Это `,(0,c.jsx)(t.code,{children:`toFiniteNumber(value) ?? 0`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`parseNumber("1 234,5"); // 1234.5
+parseNumber("abc"); // 0
+parseNumber(undefined); // 0
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Используйте её для арифметики, где невалидный вход действительно должен считаться нулём. Если отсутствие данных важно отличать от нуля, используйте `,(0,c.jsx)(t.code,{children:`toFiniteNumber`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ispositivevaluevalue`,children:(0,c.jsx)(t.code,{children:`isPositiveValue(value)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает `,(0,c.jsx)(t.code,{children:`true`}),`, только если значение успешно разобрано и строго больше нуля:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`isPositiveValue("0,1"); // true
+isPositiveValue(0); // false
+isPositiveValue(-1); // false
+isPositiveValue("abc"); // false
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`topositiveintegervalue`,children:(0,c.jsx)(t.code,{children:`toPositiveInteger(value)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает положительное целое число либо `,(0,c.jsx)(t.code,{children:`undefined`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`toPositiveInteger("12"); // 12
+toPositiveInteger("12,5"); // undefined
+toPositiveInteger(0); // undefined
+toPositiveInteger(-2); // undefined
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`iszerovaluevalue`,children:(0,c.jsx)(t.code,{children:`isZeroValue(value)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает `,(0,c.jsx)(t.code,{children:`true`}),`, если `,(0,c.jsx)(t.code,{children:`toFiniteNumber`}),` успешно получил ровно `,(0,c.jsx)(t.code,{children:`0`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`isZeroValue(0); // true
+isZeroValue(-0); // true
+isZeroValue("0,00"); // true
+isZeroValue(" 0 "); // true
+isZeroValue(""); // false
+isZeroValue(null); // false
+isZeroValue("abc"); // false
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`BigInt фактически не проходит через `,(0,c.jsx)(t.code,{children:`toFiniteNumber`}),`, поэтому `,(0,c.jsx)(t.code,{children:`0n`}),` также возвращает `,(0,c.jsx)(t.code,{children:`false`}),` в текущем публичном поведении.`]}),`
+`,(0,c.jsx)(t.h2,{id:`реестр-presets`,children:`Реестр presets`}),`
+`,(0,c.jsx)(t.h3,{id:`getnumberpresetname`,children:(0,c.jsx)(t.code,{children:`getNumberPreset(name)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает preset или `,(0,c.jsx)(t.code,{children:`undefined`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const preset = getNumberPreset("decimal-2");
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Возвращается сам объект из глобального реестра, а не clone. Не мутируйте его.`}),`
+`,(0,c.jsx)(t.h3,{id:`getnumberpresetnames`,children:(0,c.jsx)(t.code,{children:`getNumberPresetNames()`})}),`
+`,(0,c.jsx)(t.p,{children:`Возвращает новый массив имён в порядке регистрации. Подходит для UI выбора preset.`}),`
+`,(0,c.jsx)(t.h3,{id:`registernumberpresetconfig`,children:(0,c.jsx)(t.code,{children:`registerNumberPreset(config)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Регистрирует или перезаписывает preset. Все отсутствующие поля поверхностно берутся из `,(0,c.jsx)(t.code,{children:`NUMBER_FORMAT_DEFAULTS`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`registerNumberPreset({
+	name: "accounting-2",
+	decimals: 2,
+	groupingSeparator: " ",
+	decimalSeparator: ","
+});
+
+formatNumber(1234.5, "accounting-2"); // "1 234,50"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Регистрация глобальна для текущего экземпляра модуля. Выполняйте её один раз при старте приложения до компиляции formatter pipeline.`}),`
+`,(0,c.jsx)(t.p,{children:`Имя не trim-ится и поля не валидируются. Передавайте непустое устойчивое имя, не меняйте встроенные presets без явной необходимости и проверяйте числовые параметры.`}),`
+`,(0,c.jsx)(t.h3,{id:`resetnumberpresets`,children:(0,c.jsx)(t.code,{children:`resetNumberPresets()`})}),`
+`,(0,c.jsx)(t.p,{children:`Очищает реестр и восстанавливает только встроенные presets. Основной сценарий — изоляция тестов. Пользовательские presets после сброса исчезают.`}),`
+`,(0,c.jsx)(t.h3,{id:`number_format_defaults`,children:(0,c.jsx)(t.code,{children:`NUMBER_FORMAT_DEFAULTS`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`{
+	decimals: 1,
+	decimalSeparator: ",",
+	grouping: true,
+	groupingSeparator: /* ru-RU group char */,
+	groupingSize: 3
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Объект экспортируется, но не заморожен. Относитесь к нему как к read-only константе: мутация изменит будущие регистрации и сделает поведение глобально непредсказуемым.`}),`
+`,(0,c.jsx)(t.h2,{id:`объектный-preset-без-регистрации`,children:`Объектный preset без регистрации`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`formatNumber`}),` принимает готовый `,(0,c.jsx)(t.code,{children:`NumberFormatPreset`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumber(1234567.89, {
+	name: "inline",
+	decimals: 2,
+	decimalSeparator: ".",
+	grouping: true,
+	groupingSeparator: "_",
+	groupingSize: 3
+});
+// "1_234_567.89"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Такой объект не попадает в реестр. Он полезен для локального стабильного правила; переиспользуемый формат лучше зарегистрировать централизованно.`}),`
+`,(0,c.jsx)(t.p,{children:`Параметры не валидируются. Используйте:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`decimals`}),` — целое неотрицательное число в диапазоне, допустимом `,(0,c.jsx)(t.code,{children:`Intl.NumberFormat`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`groupingSize`}),` — положительное целое число;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`конечные положительные `,(0,c.jsx)(t.code,{children:`unit.value`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`известный `,(0,c.jsx)(t.code,{children:`roundingMode`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Нулевой или отрицательный `,(0,c.jsx)(t.code,{children:`groupingSize`}),` в ручной ветке группировки может привести к незавершающемуся циклу. Не передавайте непроверенный пользовательский объект напрямую.`]}),`
+`,(0,c.jsx)(t.h2,{id:`truncatenumbernum-decimals`,children:(0,c.jsx)(t.code,{children:`truncateNumber(num, decimals)`})}),`
+`,(0,c.jsx)(t.p,{children:`Низкоуровневая математическая функция усекает дробную часть без округления:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`truncateNumber(123.789, 1); // 123.7
+truncateNumber(-123.789, 1); // -123.7
+truncateNumber(123.789, 0); // 123
+truncateNumber(123.789, -1); // 120
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Функция не валидирует параметры и не используется обычным `,(0,c.jsx)(t.code,{children:`formatNumber`}),` для standard presets.`]}),`
+`,(0,c.jsxs)(t.h2,{id:`кеш-intlnumberformat`,children:[`Кеш `,(0,c.jsx)(t.code,{children:`Intl.NumberFormat`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль кеширует formatter по комбинации `,(0,c.jsx)(t.code,{children:`decimals + grouping`}),`, что важно для сотен ячеек таблицы.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`clearFormatCache();
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`clearFormatCache`}),` очищает только кеш `,(0,c.jsx)(t.code,{children:`Intl.NumberFormat`}),`. Она не очищает и не сбрасывает реестр presets. В прикладном коде вызывать её обычно не нужно.`]}),`
+`,(0,c.jsx)(t.h2,{id:`практические-рецепты`,children:`Практические рецепты`}),`
+`,(0,c.jsx)(t.h3,{id:`безопасный-вывод-значения-api`,children:`Безопасный вывод значения API`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const parsed = toFiniteNumber(response.amount);
+const amountText = parsed === undefined ? "—" : formatNumberAsDecimal2(parsed);
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`поле-где-ноль-нужно-скрыть`,children:`Поле, где ноль нужно скрыть`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const text = formatNumberAsIntegerOrEmpty(row.count);
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`проверка-положительного-page-size`,children:`Проверка положительного page size`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const pageSize = toPositiveInteger(search.pageSize) ?? 20;
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`собственный-preset-на-старте-приложения`,children:`Собственный preset на старте приложения`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`export function configureFormatters(): void {
+	registerNumberPreset({
+		name: "quantity-4",
+		decimals: 4,
+		grouping: false
+	});
+}
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsxs)(t.h3,{id:`передавать-локализованную-строку-прямо-в-formatnumber`,children:[`Передавать локализованную строку прямо в `,(0,c.jsx)(t.code,{children:`formatNumber`})]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Неправильно
+formatNumber("1 234,5", "decimal-2"); // "0"
+
+// Правильно
+const parsed = toFiniteNumber("1 234,5");
+const text = parsed === undefined ? "—" : formatNumber(parsed, "decimal-2");
+`})}),`
+`,(0,c.jsxs)(t.h3,{id:`считать-percent-математическим-процентом`,children:[`Считать `,(0,c.jsx)(t.code,{children:`percent`}),` математическим процентом`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Preset не умножает `,(0,c.jsx)(t.code,{children:`0.25`}),` на 100 и не добавляет `,(0,c.jsx)(t.code,{children:`%`}),`. Он выведет `,(0,c.jsx)(t.code,{children:`0,25`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-валютный-символ`,children:`Ожидать валютный символ`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`currency`}),` и `,(0,c.jsx)(t.code,{children:`price`}),` форматируют число, но не знают валюту.`]}),`
+`,(0,c.jsx)(t.h3,{id:`мутировать-полученный-preset`,children:`Мутировать полученный preset`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`getNumberPreset`}),` возвращает реестровый объект. Создайте новый объект или вызовите `,(0,c.jsx)(t.code,{children:`registerNumberPreset`}),` с полной новой конфигурацией.`]}),`
+`,(0,c.jsx)(t.h3,{id:`регистрировать-preset-во-время-рендера`,children:`Регистрировать preset во время рендера`}),`
+`,(0,c.jsx)(t.p,{children:`Это глобальное изменение. Настраивайте реестр один раз до построения runtime.`}),`
+`,(0,c.jsx)(t.h2,{id:`api-справка`,children:`API-справка`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Семейство`}),(0,c.jsx)(t.th,{children:`Публичный API`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Универсальное форматирование`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatNumber`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Готовые форматы`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`formatNumberAsInteger`}),`, `,(0,c.jsx)(t.code,{children:`formatNumberAsCurrency`}),`, `,(0,c.jsx)(t.code,{children:`formatNumberAsDecimal`}),`, `,(0,c.jsx)(t.code,{children:`formatNumberAsDecimal2`}),`, `,(0,c.jsx)(t.code,{children:`formatNumberAsDecimal3`}),`, `,(0,c.jsx)(t.code,{children:`formatNumberAsPercent`}),`, `,(0,c.jsx)(t.code,{children:`formatNumberAsPrice`}),`, `,(0,c.jsx)(t.code,{children:`formatNumberAsTonnage`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Ноль как пустое`}),(0,c.jsxs)(t.td,{children:[`все перечисленные wrappers с суффиксом `,(0,c.jsx)(t.code,{children:`OrEmpty`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Парсинг`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`toFiniteNumber`}),`, `,(0,c.jsx)(t.code,{children:`parseNumber`}),`, `,(0,c.jsx)(t.code,{children:`isPositiveValue`}),`, `,(0,c.jsx)(t.code,{children:`toPositiveInteger`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Проверка нуля`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`isZeroValue`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Presets`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`DEFAULT_NUMBER_PRESET_NAMES`}),`, `,(0,c.jsx)(t.code,{children:`NUMBER_FORMAT_DEFAULTS`}),`, `,(0,c.jsx)(t.code,{children:`getNumberPreset`}),`, `,(0,c.jsx)(t.code,{children:`getNumberPresetNames`}),`, `,(0,c.jsx)(t.code,{children:`registerNumberPreset`}),`, `,(0,c.jsx)(t.code,{children:`resetNumberPresets`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Низкоуровневое`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`truncateNumber`}),`, `,(0,c.jsx)(t.code,{children:`clearFormatCache`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Типы`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`NumberFormatPreset`}),`, `,(0,c.jsx)(t.code,{children:`NumberFormatPresetConfig`}),`, `,(0,c.jsx)(t.code,{children:`NumberFormatCompactOptions`}),`, `,(0,c.jsx)(t.code,{children:`NumberFormatCompactUnit`}),`, `,(0,c.jsx)(t.code,{children:`NumberFormatCompactRoundingMode`})]})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`formatCompactNumber`}),`, `,(0,c.jsx)(t.code,{children:`formatNumberAsChartAxis`}),` и `,(0,c.jsx)(t.code,{children:`resolveNumberPreset`}),` не входят в публичный entrypoint. Compact-поведение доступно через встроенные или собственные presets.`]}),`
+`,(0,c.jsx)(t.h2,{id:`связанная-документация`,children:`Связанная документация`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:(0,c.jsxs)(t.a,{href:`../README.mdx`,children:[`Обзор `,(0,c.jsx)(t.code,{children:`formatters`})]})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`../strings/README.mdx`,children:`Строковая нормализация`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsx)(t.a,{href:`../pipeline/README.mdx`,children:`Formatter pipeline`})}),`
+`]})]})}function s(e={}){let{wrapper:t}={...n(),...e.components};return t?(0,c.jsx)(t,{...e,children:(0,c.jsx)(o,{...e})}):o(e)}var c;function l(){return(l=e((()=>{c=t(),r(),a()})))()}l();export{s as default};