@ryuzaki13/react-foundation-lib 2.32.0 → 2.34.0

package/src/formatters/number/README.mdx

@@ -74,6 +74,7 @@ const text = value === undefined ? "Некорректно" : formatNumber(value
 | `currency`               |              0 | Денежное число без символа валюты                          |
 | `price`                  |              0 | Цена без символа валюты                                    |
 | `percent`                |              2 | Процентное число без автоматического умножения и знака `%` |
+| `ratio-percent`          |              2 | Доля с процентным масштабированием и знаком `%`            |
 | `tonnage`                |              1 | Тоннаж                                                     |
 | `compact-currency`       |              0 | Компактное число, усечение                                 |
 | `compact-currency-round` |              0 | Компактное число, округление                               |
@@ -97,6 +98,38 @@ import { DEFAULT_NUMBER_PRESET_NAMES, formatNumber } from "@ryuzaki13/react-foun
 formatNumber(1234.5, DEFAULT_NUMBER_PRESET_NAMES.decimal2);
 ```
 
+## Числовой процент и доля
+
+`percent` и `formatNumberAsPercent` форматируют уже подготовленное число с двумя дробными знаками. `ratio-percent` принимает долю: числу `0.2` соответствует отображение `20,00%`. Передавать предварительно умноженное на 100 значение для этого preset не нужно.
+
+```ts
+import {
+	DEFAULT_NUMBER_PRESET_NAMES,
+	NUMBER_PRESET_NAME_RATIO_PERCENT,
+	formatNumber,
+	formatNumberAsPercent
+} from "@ryuzaki13/react-foundation-lib/formatters";
+
+formatNumber(0.2, "percent"); // "0,20"
+formatNumberAsPercent(0.2); // "0,20"
+formatNumber(0.2, NUMBER_PRESET_NAME_RATIO_PERCENT); // "20,00%"
+formatNumber(1, DEFAULT_NUMBER_PRESET_NAMES.ratioPercent); // "100,00%"
+formatNumber(0, "ratio-percent"); // "0,00%"
+```
+
+Число остаётся неизменным; процентное масштабирование относится только к представлению. Для formatter pipeline достаточно обычного `typedValueFormat` с `numberPresetName: "ratio-percent"`, в том числе у числовой колонки с целочисленным типом `int`. Смена preset не изменяет числовую семантику формул.
+
+Необязательное поле `NumberFormatPreset.style` задаёт способ представления: отсутствие поля или `"decimal"` сохраняет обычный числовой формат, `"percent"` отображает долю со знаком `%`. Встроенный `ratio-percent` использует два дробных знака, собственный preset использует свой `decimals`:
+
+```ts
+registerNumberPreset({ name: "ratio-3", style: "percent", decimals: 3 });
+formatNumber(0.12345, "ratio-3"); // "12,345%"
+```
+
+`style: "percent"` нельзя сочетать с `compact`: такая комбинация явно отклоняется. Существующие compact presets без marker сохраняют своё поведение.
+
+При экспорте через `createTableExcelColumn` из `/excel` этот style создаёт native percentage mask с точностью preset. В строку книги передаётся исходное число `0.2`, а Excel отображает процент. Готовую строку `"20%"` или число `20` вместо доли передавать не следует. Формат старого `percent` остаётся обычным числовым.
+
 ## `formatNumber(value, presetOrName)`
 
 ```ts
@@ -109,7 +142,7 @@ function formatNumber(value: unknown, presetOrName: string | NumberFormatPreset)
 2. вызывает `Number(value)`;
 3. для `NaN` и бесконечности возвращает `"0"`;
 4. находит preset по имени или использует переданный объект;
-5. округляет и форматирует число;
+5. округляет и форматирует число с учётом выбранного `style`;
 6. применяет compact-семантику, если она задана.
 
 ```ts
@@ -175,7 +208,7 @@ formatNumberAsCurrency(1250); // "1 250", без ₽
 formatNumberAsPercent(12.5); // "12,50", без %
 ```
 
-Если нужен суффикс, добавляйте его на UI-уровне или используйте специализированный модуль единиц измерения.
+Для доли со знаком `%` используйте `ratio-percent`. Другие суффиксы добавляйте на UI-уровне или используйте специализированный модуль единиц измерения.
 
 ## Wrappers `OrEmpty`
 
@@ -388,7 +421,7 @@ formatNumber(1234.5, "accounting-2"); // "1 234,50"
 
 Регистрация глобальна для текущего экземпляра модуля. Выполняйте её один раз при старте приложения до компиляции formatter pipeline.
 
-Имя не trim-ится и поля не валидируются. Передавайте непустое устойчивое имя, не меняйте встроенные presets без явной необходимости и проверяйте числовые параметры.
+Имя не trim-ится. Передавайте непустое устойчивое имя, не меняйте встроенные presets без явной необходимости и проверяйте числовые параметры. Сочетание `style: "percent"` с `compact` не поддерживается и отклоняется при регистрации или разрешении preset.
 
 ### `resetNumberPresets()`
 
@@ -426,7 +459,7 @@ formatNumber(1234567.89, {
 
 Такой объект не попадает в реестр. Он полезен для локального стабильного правила; переиспользуемый формат лучше зарегистрировать централизованно.
 
-Параметры не валидируются. Используйте:
+Числовые параметры автоматически не валидируются. Используйте:
 
 - `decimals` — целое неотрицательное число в диапазоне, допустимом `Intl.NumberFormat`;
 - `groupingSize` — положительное целое число;
@@ -450,7 +483,7 @@ truncateNumber(123.789, -1); // 120
 
 ## Кеш `Intl.NumberFormat`
 
-Модуль кеширует formatter по комбинации `decimals + grouping`, что важно для сотен ячеек таблицы.
+Модуль кеширует formatter по комбинации `style + decimals + grouping`, что важно для сотен ячеек таблицы. Числовой и процентный режимы не используют один formatter даже при одинаковой точности.
 
 ```ts
 clearFormatCache();
@@ -506,7 +539,7 @@ const text = parsed === undefined ? "—" : formatNumber(parsed, "decimal-2");
 
 ### Считать `percent` математическим процентом
 
-Preset не умножает `0.25` на 100 и не добавляет `%`. Он выведет `0,25`.
+Preset не умножает `0.25` на 100 и не добавляет `%`. Он выведет `0,25`. Для отображения доли как `25,00%` выбирайте `ratio-percent`.
 
 ### Ожидать валютный символ
 
@@ -529,7 +562,7 @@ Preset не умножает `0.25` на 100 и не добавляет `%`. О
 | Ноль как пустое              | все перечисленные wrappers с суффиксом `OrEmpty`                                                                                                                                                        |
 | Парсинг                      | `toFiniteNumber`, `parseNumber`, `isPositiveValue`, `toPositiveInteger`                                                                                                                                 |
 | Проверка нуля                | `isZeroValue`                                                                                                                                                                                           |
-| Presets                      | `DEFAULT_NUMBER_PRESET_NAMES`, `NUMBER_FORMAT_DEFAULTS`, `getNumberPreset`, `getNumberPresetNames`, `registerNumberPreset`, `resetNumberPresets`                                                        |
+| Presets                      | `DEFAULT_NUMBER_PRESET_NAMES`, `NUMBER_PRESET_NAME_RATIO_PERCENT`, `NUMBER_FORMAT_DEFAULTS`, `getNumberPreset`, `getNumberPresetNames`, `registerNumberPreset`, `resetNumberPresets`                    |
 | Низкоуровневое               | `truncateNumber`, `clearFormatCache`                                                                                                                                                                    |
 | Типы                         | `NumberFormatPreset`, `NumberFormatPresetConfig`, `NumberFormatCompactOptions`, `NumberFormatCompactUnit`, `NumberFormatCompactRoundingMode`                                                            |
 
@@ -540,3 +573,4 @@ Preset не умножает `0.25` на 100 и не добавляет `%`. О
 - [Обзор `formatters`](../README.mdx)
 - [Строковая нормализация](../strings/README.mdx)
 - [Formatter pipeline](../pipeline/README.mdx)
+- [Excel](../../excel/README.mdx)

package/src/formulas/README.mdx

@@ -6,7 +6,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 Модуль `@ryuzaki13/react-foundation-lib/formulas` предоставляет безопасную инфраструктуру для заранее написанных клиентских формул таблицы.
 
-Формула получает значения полей текущей строки и числовые константы, выполняет синхронный расчёт и возвращает конечное JavaScript-число. Например, она может вычислить сумму, разницу, отношение или процент для calculated-колонки.
+Формула получает значения полей текущей строки и числовые константы либо заранее подготовленные host-приложением позиции, выполняет синхронный расчёт и возвращает конечное JavaScript-число. Например, она может вычислить сумму, разницу, отношение или процент для calculated-колонки.
 
 ```text
 данные строки + упорядоченные зависимости
@@ -30,6 +30,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 - [Чтение активного реестра](#чтение-активного-реестра)
 - [Выполнение формулы](#выполнение-формулы)
 - [Предварительная компиляция](#предварительная-компиляция)
+- [Заранее разрешённые аргументы](#заранее-разрешённые-аргументы)
 - [Валидация зависимостей](#валидация-зависимостей)
 - [Интеграция с formatter pipeline](#интеграция-с-formatter-pipeline)
 - [Отличие от row-based formatter](#отличие-от-row-based-formatter)
@@ -50,6 +51,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 - хранит один активный реестр в текущем экземпляре модуля;
 - выполняет формулы без выбрасывания их runtime-ошибок наружу;
 - компилирует formula + keys в переиспользуемый executor;
+- исполняет ту же зарегистрированную функцию над готовыми позиционными значениями без промежуточных полей строки;
 - проверяет существование формулы и корректность выбранных dependencies;
 - сообщает, какие dependency indexes реально использовала формула на тестовых данных.
 
@@ -68,7 +70,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 Host-приложение владеет прикладными `TableFormulaDefinition`: оно объявляет их в коде, тестирует, собирает в реестр и устанавливает на старте приложения.
 
-Сериализуемая конфигурация колонки хранит только стабильный `formulaId` и ordered dependencies. Реальная функция остаётся доверенным кодом приложения.
+В row-only API сериализуемая конфигурация колонки хранит стабильный `formulaId` и ordered dependencies. Реальная функция остаётся доверенным кодом приложения.
 
 ## Импорт
 
@@ -77,16 +79,21 @@ Host-приложение владеет прикладными `TableFormulaDef
 ```ts
 import {
 	compileTableFormula,
+	compileTableFormulaWithResolvedArguments,
 	configureTableFormulaRegistry,
 	createTableFormulaRegistry,
 	executeTableFormula,
+	executeTableFormulaWithResolvedArguments,
 	getTableFormulaById,
 	getTableFormulaList,
 	formatTableFormulaExpression,
-	validateTableFormulaDependencies
+	validateTableFormulaDependencies,
+	type TableFormulaDefinition,
+	type TableFormulaExecutionResult,
+	type TableFormulaRegistry,
+	type TableFormulaResolvedArgument,
+	type TableFormulaResolvedExecutor
 } from "@ryuzaki13/react-foundation-lib/formulas";
-
-import type { TableFormulaDefinition, TableFormulaExecutionResult, TableFormulaRegistry } from "@ryuzaki13/react-foundation-lib/formulas";
 ```
 
 Корневой импорт пакета и private imports из исходников не поддерживаются:
@@ -365,7 +372,7 @@ interface TableFormulaContext {
 
 ### `ctx.key(index)`
 
-Возвращает id dependency по индексу:
+В row-only API возвращает id dependency по индексу:
 
 ```ts
 // keys = ["planned", "actual"]
@@ -380,6 +387,8 @@ ctx.key(1.5); // undefined
 
 Пустая строка технически может вернуться из `key`, если она была передана в `keys`, но `value` и `num` считают пустой key отсутствующим. Используйте только непустые dependency ids.
 
+Для [заранее разрешённых аргументов](#заранее-разрешённые-аргументы) key передаёт host; он не используется для поиска значения в строке.
+
 ### `ctx.value(index)`
 
 Возвращает исходное значение без преобразования:
@@ -389,7 +398,7 @@ ctx.key(1.5); // undefined
 ctx.value(1); // "25"
 ```
 
-Для константы возвращается непосредственно её числовое значение. Для неправильного индекса, пустого key или отсутствующего свойства возвращается `undefined`.
+В row-only API для константы возвращается непосредственно её числовое значение. Для неправильного индекса, пустого key или отсутствующего свойства возвращается `undefined`. Для готовых позиций действуют [правила разрешённых аргументов](#заранее-разрешённые-аргументы).
 
 Используйте `value`, когда нужно отличать отсутствующее значение от нуля или применять собственный parser:
 
@@ -809,9 +818,69 @@ if (compiled.ok) {
 
 ### Синхронность и повторный вход
 
-Compiled executor переиспользует один context с изменяемой внутренней ссылкой на `rowData`. Это безопасно для обычной синхронной формулы.
+Executor `compileTableFormula` переиспользует один context с изменяемой внутренней ссылкой на `rowData`. Это безопасно для обычной синхронной формулы.
+
+Не делайте formula `async`, не сохраняйте `ctx` во внешнем state и не запускайте тот же row-only executor рекурсивно из formula. Такой код нарушает lifecycle переиспользуемого context. Отдельный контракт повторного входа для готовых позиций описан ниже.
+
+## Заранее разрешённые аргументы
+
+Когда значения относятся к разным строкам или вычисляются host-приложением, передайте их в позициях непосредственно. Используются существующие `TableFormulaDefinition`, registry и методы `ctx.key`, `ctx.value`, `ctx.num`; новую арифметическую функцию для другого источника писать не требуется.
+
+```ts
+type TableFormulaResolvedArgument = {
+	readonly value: unknown;
+	readonly key?: string;
+};
+
+type TableFormulaResolvedExecutor = (resolvedArguments: readonly TableFormulaResolvedArgument[]) => TableFormulaExecutionResult;
+```
+
+### Подготовка и выполнение
+
+Реестр из быстрого старта уже содержит `sum`. Host получает значения до вызова runtime и сохраняет нужный порядок:
+
+```ts
+import {
+	compileTableFormulaWithResolvedArguments,
+	executeTableFormulaWithResolvedArguments,
+	type TableFormulaResolvedArgument
+} from "@ryuzaki13/react-foundation-lib/formulas";
+
+const resolvedArguments: readonly TableFormulaResolvedArgument[] = [
+	{ value: 20, key: "amount" }, // Поле текущей строки.
+	{ value: 100 } // Уже полученное host-ом значение другой строки.
+];
+
+const result = executeTableFormulaWithResolvedArguments({ formulaId: "sum", arguments: resolvedArguments });
+// result: { ok: true, value: 120 }
+
+const compiled = compileTableFormulaWithResolvedArguments({ formulaId: "sum" });
+
+if (compiled.ok) {
+	const first = compiled.execute(resolvedArguments);
+	const second = compiled.execute([{ value: 30, key: "amount" }, { value: 200 }]);
+	// first.value === 120, second.value === 230 при успешном результате.
+}
+```
+
+Compile result содержит либо `ok: true` и `execute: TableFormulaResolvedExecutor`, либо `ok: false, reason: "formula_not_found"`. Массив передаётся при каждом execute, а не при compile. Для разового вычисления `executeTableFormulaWithResolvedArguments` выполняет compile и один вызов executor.
+
+### Значения, ключи и границы
+
+- `value(index)` возвращает переданный `value` буквально, включая `null`, `undefined`, число или числовую строку. Значение не ищется в `rowData`; `key` не влияет на его чтение.
+- Host задаёт `key` только для поля текущей строки. Для константы и внешнего источника его опускают, поэтому `key(index)` возвращает `undefined`. Не создавайте фиктивные ID вроде `TOTAL:Amount`.
+- Порядок и повторы сохраняются. Для отрицательного, нецелого или вышедшего за массив индекса `key()` и `value()` возвращают `undefined`, `num()` — `0`.
+- `num()` использует [действующее числовое преобразование](#числовое-преобразование-ctxnum). Исключение преобразования даёт `runtime_error`, а не успешный ноль.
+- Каждая позиция содержит собственное поле `value`: `{ value: undefined }` корректен, дырка массива или запись без `value` дают `runtime_error`. Ошибка подготовки не подменяется временным нулём.
+- Используется существующий `TableFormulaExecutionResult`: не конечный результат формулы даёт `invalid_result`, исключение — `runtime_error`. Значения и текст исключения не добавляются в результат ошибки.
+
+### Время жизни и ответственность host
+
+Compiled executor сохраняет зарегистрированную функцию без массива аргументов. Контекст создаётся для отдельного синхронного вызова, поэтому вложенное выполнение того же executor не подменяет значения внешнего или следующего вызова. Входные массивы и записи не изменяются; значения не нормализуются и не копируются глубоко. Формулы остаются чистыми и синхронными; `ctx` нельзя сохранять для чтения после завершения вызова.
+
+Host владеет сериализуемой ссылкой на источник, её доступностью, загрузкой, выбором исходного или вычисленного значения и проверкой циклов. Для ожидания данных он может явно подготовить `{ value: 0 }`, сохраняя состояние загрузки и диагностику отдельно. Runtime не получает DataSource callbacks и не разрешает ИТОГО или родителя самостоятельно.
 
-Не делайте formula `async`, не сохраняйте `ctx` во внешнем state и не запускайте тот же executor рекурсивно из formula. Такой код нарушает lifecycle переиспользуемого context.
+`TableFormulaDependency`, row-only compile/execute, validator зависимостей, formatter выражения и formatter pipeline сохраняют свои контракты. `validateTableFormulaDependencies` не проверяет адреса внешних источников, а `formatTableFormulaExpression` не строит для них scoped preview. Готовые позиции — вход текущего выполнения, а не новый формат сохранённой конфигурации.
 
 ## Валидация зависимостей
 
@@ -862,7 +931,7 @@ Validator:
 | ------------------------------- | ----------------------------------------------------------- |
 | `formula_not_found`             | Formula id отсутствует в registry                           |
 | `dependency_not_available`      | Dependency id отсутствует среди доступных колонок           |
-| `invalid_constant`              | Константа не содержит конечное числовое значение             |
+| `invalid_constant`              | Константа не содержит конечное числовое значение            |
 | `dependency_index_out_of_range` | Formula прочитала index, для которого dependency не передан |
 
 ### Warnings
@@ -1165,7 +1234,7 @@ expect(
 быстрее:   compileTableFormula один раз → execute(rowData) для каждой строки
 ```
 
-Compiled executor переиспользует context и не делает registry lookup на каждую строку.
+Executor `compileTableFormula` переиспользует context и не делает registry lookup на каждую строку. `compileTableFormulaWithResolvedArguments` также находит функцию один раз, но создаёт отдельный контекст на каждый вызов; значения host подготавливает перед execute.
 
 Formatter pipeline уже использует этот подход: runtime field компилируется на construction-stage.
 
@@ -1235,42 +1304,46 @@ Promise не является конечным number и даст `invalid_resul
 
 ### Runtime functions
 
-| API                                | Назначение                       | Важное поведение                                        |
-| ---------------------------------- | -------------------------------- | ------------------------------------------------------- |
-| `createTableFormulaContext`        | Создать context вручную          | Копирует keys, но не rowData; `num` использует `Number` |
-| `createTableFormulaRegistry`       | Собрать нормализованный registry | Бросает `Error` для пустого/повторного id               |
-| `configureTableFormulaRegistry`    | Установить активный registry     | Полностью заменяет module-level registry                |
-| `getTableFormulaList`              | Получить ordered catalog         | Возвращает тот же readonly list                         |
-| `getTableFormulaById`              | Найти definition                 | Trim id; `undefined` для пустого/неизвестного           |
-| `formatTableFormulaExpression`     | Подставить ID в шаблон превью    | Сохраняет незаполненные `$n`; не исполняет выражение    |
-| `compileTableFormula`              | Подготовить reusable executor    | Фиксирует formula и копирует keys                       |
-| `executeTableFormula`              | Compile + один execute           | Возвращает controlled result, не бросает formula error  |
-| `validateTableFormulaDependencies` | Проверить mapping dependencies   | Дважды исполняет formula на synthetic data              |
+| API                                        | Назначение                           | Важное поведение                                        |
+| ------------------------------------------ | ------------------------------------ | ------------------------------------------------------- |
+| `createTableFormulaContext`                | Создать context вручную              | Копирует keys, но не rowData; `num` использует `Number` |
+| `createTableFormulaRegistry`               | Собрать нормализованный registry     | Бросает `Error` для пустого/повторного id               |
+| `configureTableFormulaRegistry`            | Установить активный registry         | Полностью заменяет module-level registry                |
+| `getTableFormulaList`                      | Получить ordered catalog             | Возвращает тот же readonly list                         |
+| `getTableFormulaById`                      | Найти definition                     | Trim id; `undefined` для пустого/неизвестного           |
+| `formatTableFormulaExpression`             | Подставить ID в шаблон превью        | Сохраняет незаполненные `$n`; не исполняет выражение    |
+| `compileTableFormula`                      | Подготовить reusable executor        | Фиксирует formula и копирует keys                       |
+| `executeTableFormula`                      | Compile + один execute               | Возвращает controlled result, не бросает formula error  |
+| `compileTableFormulaWithResolvedArguments` | Подготовить executor готовых позиций | Фиксирует функцию; аргументы передаются при execute     |
+| `executeTableFormulaWithResolvedArguments` | Выполнить готовые позиции один раз   | Использует тот же registry и execution result           |
+| `validateTableFormulaDependencies`         | Проверить mapping dependencies       | Дважды исполняет formula на synthetic data              |
 
 ### Публичные TypeScript-типы
 
-| Тип                                        | Назначение                                 |
-| ------------------------------------------ | ------------------------------------------ |
-| `TableFormulaRowData`                      | Строка `Record<string, unknown>`           |
+| Тип                                        | Назначение                                      |
+| ------------------------------------------ | ----------------------------------------------- |
+| `TableFormulaRowData`                      | Строка `Record<string, unknown>`                |
 | `TableFormulaDependency`                   | ID поля либо объект конечной числовой константы |
-| `TableFormulaContext`                      | Методы `key`, `value`, `num`               |
-| `TableFormulaFn`                           | Синхронная function `context → number`     |
-| `TableFormulaDefinition`                   | Metadata и function одной formula          |
-| `TableFormulaRegistry`                     | Readonly `list` + `byId`                   |
-| `TableFormulaExecutionResult`              | Success/error результат execute            |
-| `TableFormulaCompiledExecutor`             | Переиспользуемый `(rowData) → result`      |
-| `TableFormulaValidationMessage`            | `{ code, message }` validation diagnostics |
-| `TableFormulaDependenciesValidationResult` | Errors, warnings и usage dependencies      |
+| `TableFormulaContext`                      | Методы `key`, `value`, `num`                    |
+| `TableFormulaFn`                           | Синхронная function `context → number`          |
+| `TableFormulaDefinition`                   | Metadata и function одной formula               |
+| `TableFormulaRegistry`                     | Readonly `list` + `byId`                        |
+| `TableFormulaExecutionResult`              | Success/error результат execute                 |
+| `TableFormulaCompiledExecutor`             | Переиспользуемый `(rowData) → result`           |
+| `TableFormulaResolvedArgument`             | Готовое `value` и optional `key` позиции        |
+| `TableFormulaResolvedExecutor`             | Переиспользуемый `(resolvedArguments) → result` |
+| `TableFormulaValidationMessage`            | `{ code, message }` validation diagnostics      |
+| `TableFormulaDependenciesValidationResult` | Errors, warnings и usage dependencies           |
 
 `ValidationCode`, instrumentation type и compile-result type не экспортируются как именованные публичные типы. Их конкретные значения доступны через публичные function signatures и unions, описанные выше.
 
 ### Причины execution error
 
-| Reason              | Значение                                |
-| ------------------- | --------------------------------------- |
-| `formula_not_found` | Formula отсутствует в активном registry |
-| `invalid_result`    | Function вернула не конечный number     |
-| `runtime_error`     | Function выбросила исключение           |
+| Reason              | Значение                                                              |
+| ------------------- | --------------------------------------------------------------------- |
+| `formula_not_found` | Formula отсутствует в активном registry                               |
+| `invalid_result`    | Function вернула не конечный number                                   |
+| `runtime_error`     | Некорректные готовые позиции или исключение выполнения/преобразования |
 
 ### Validation codes