@ryuzaki13/react-foundation-lib 1.2.4 → 1.2.6

package/src/docs/filesAndExcel.mdx

@@ -0,0 +1,163 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Файлы и Excel" />
+
+# Файлы, бинарные данные и Excel
+
+Эта страница описывает browser-only API для чтения пользовательских файлов, преобразования base64 и формирования `.xlsx`. Подготовка бизнес-полей, проверка прав доступа и отправка файла на сервер остаются ответственностью host-приложения.
+
+## `file`: чтение файлов и HTTP-заголовки
+
+```ts
+import {
+	createContentDispositionHeader,
+	readFile,
+	readImageFile,
+	resolveMimeTypeByExtension,
+	type ReadFileError,
+	type ReadImageError
+} from "@ryuzaki13/react-foundation-lib/file";
+```
+
+### Когда использовать
+
+- `readFile` — получить `dataUrl` для preview или `ArrayBuffer` для дальнейшей обработки;
+- `readImageFile` — то же для изображений с проверкой image MIME и размером изображения;
+- helpers Content-Disposition — сформировать безопасный заголовок в browser-compatible/edge runtime коде;
+- `resolveMimeTypeByExtension` — определить MIME по расширению, если содержимого для sniffing нет.
+
+### `readFile`
+
+```ts
+readFile(file, options?): Promise<ReadFileResult>
+```
+
+| Опция                             | Назначение                                        |
+| --------------------------------- | ------------------------------------------------- |
+| `mode?: "data-url"`               | Режим по умолчанию. Результат содержит `dataUrl`. |
+| `mode: "array-buffer"`            | Результат содержит `buffer`.                      |
+| `allowedMime?: readonly string[]` | Точный список разрешённых MIME.                   |
+| `maxBytes?: number`               | Максимальный размер файла в байтах.               |
+| `signal?: AbortSignal`            | Отменяет чтение через `FileReader.abort()`.       |
+
+Возвращаемый discriminated union всегда содержит `file` и `meta` (`name`, `mime`, `size`, `lastModified`). После проверки `result.mode` TypeScript раскрывает либо `dataUrl`, либо `buffer`.
+
+```ts
+const result = await readFile(file, {
+	mode: "data-url",
+	allowedMime: ["application/pdf"],
+	maxBytes: 10 * 1024 * 1024,
+	signal
+});
+
+if (result.mode === "data-url") {
+	previewUrl = result.dataUrl;
+}
+```
+
+`ReadFileError` имеет предсказуемый `code`: `NO_FILE`, `MIME_NOT_ALLOWED`, `FILE_TOO_LARGE`, `READ_ABORTED` или `READ_FAILED`. Обрабатывайте его как ожидаемую ошибку выбора файла, а остальные ошибки не скрывайте.
+
+### `readImageFile`
+
+```ts
+readImageFile(image, options?): Promise<ReadImageResult>
+```
+
+Поддерживаемые `ImageMime`: `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/svg+xml`, `image/avif`. В режиме `data-url` результат дополнительно включает `dimensions` (`width`, `height`). В режиме `array-buffer` декодирование изображения не выполняется.
+
+`ReadImageError` расширяет коды `ReadFileError` значениями `NOT_AN_IMAGE` и `IMAGE_DECODE_FAILED`.
+
+### Дополнительный API `file`
+
+| API                                             | Контракт                                                                                                              |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `buildMeta(file)`                               | Возвращает serializable метаданные `FileMeta`.                                                                        |
+| `attachAbort(signal, reader)`                   | Привязывает отмену к `FileReader`; возвращённую функцию cleanup вызывают только custom consumers низкоуровневого API. |
+| `assertNotAborted(signal?)`                     | Бросает `ReadFileError("READ_ABORTED")`, если сигнал уже отменён.                                                     |
+| `assertValidAllowedMime`, `assertValidAccept`   | Проверяют конфигурацию accept/MIME до чтения.                                                                         |
+| `sanitizeFileName(value, fallback?)`            | Удаляет unsafe символы из имени.                                                                                      |
+| `encodeFilenameRFC5987(value)`                  | Кодирует Unicode filename для HTTP header.                                                                            |
+| `createAsciiFilenameFallback(value, fallback?)` | Создаёт ASCII fallback для старых consumers заголовка.                                                                |
+| `createContentDispositionHeader(options)`       | Создаёт `inline`/`attachment` Content-Disposition с `filename` и `filename*`.                                         |
+
+## `binary`: base64 → `Blob`
+
+```ts
+import { binaryToBlob, detectMimeType, useBinaryFile } from "@ryuzaki13/react-foundation-lib/binary";
+```
+
+| API                                              | Вход и результат                                                                                                                  |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `binaryToBlob(binaryData, mimeType?, isBase64?)` | Создаёт `Blob` из base64/data URL (по умолчанию) или raw binary string (`false`). Пустые или некорректные данные бросают `Error`. |
+| `detectMimeType(fileName?, binaryData?)`         | Ищет MIME по расширению, data URL, затем сигнатуре base64. Неопределённый документ трактует как `application/pdf`.                |
+| `useBinaryFile(bin)`                             | React hook, возвращает `{ data: { blob, mime } \| null, error: string \| null }`.                                                 |
+
+```ts
+const mime = detectMimeType("report.pdf", base64);
+const blob = binaryToBlob(base64, mime);
+const objectUrl = URL.createObjectURL(blob);
+
+// Владелец UI обязан освободить URL при смене файла/размонтировании.
+URL.revokeObjectURL(objectUrl);
+```
+
+`useBinaryFile` не создаёт object URL и не освобождает его: это lifecycle конкретного preview-компонента. Hook использует `Blob` и `atob`, поэтому не вызывайте его в SSR или worker без совместимого polyfill.
+
+## `excel`: скачивание `.xlsx`
+
+```ts
+import {
+	buildExcelAutoFilterRef,
+	buildExcelSheetData,
+	createTableExcelColumn,
+	downloadExcelFile,
+	downloadExcelWorkbook,
+	downloadResolvedExcelTable,
+	downloadResolvedExcelWorkbook,
+	resolveExcelCellStyleFromState,
+	resolveExcelSheetNames
+} from "@ryuzaki13/react-foundation-lib/excel";
+```
+
+### Базовый экспорт
+
+`downloadExcelFile({ fileName, columns, rows, autoFilter?, getCellStyle? })` создаёт один лист; `downloadExcelWorkbook({ fileName, sheets })` — книгу из нескольких листов. Это asynchronous browser API, который инициирует скачивание через `write-excel-file`.
+
+```ts
+await downloadExcelFile({
+	fileName: "users.xlsx",
+	columns: [
+		{ id: "name", header: "Имя", type: String, width: 28 },
+		{ id: "createdAt", header: "Дата", type: Date, format: "dd.mm.yyyy" }
+	],
+	rows: [{ name: "Анна", createdAt: new Date("2026-07-30") }],
+	autoFilter: true
+});
+```
+
+| Public type/API                             | Назначение                                                                                                           |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `ExcelColumn`, `ExcelRow`, `ExcelCellStyle` | Контракты столбца, строки и стиля ячейки. `type` передаёт в файл истинные `Number`/`Date`/`Boolean`, а не UI-строку. |
+| `buildExcelSheetData(args)`                 | Строит данные листа без запуска download; подходит для тестируемой подготовки.                                       |
+| `buildExcelAutoFilterRef(columns, rows)`    | Даёт Excel-диапазон или `undefined` для пустой сетки.                                                                |
+| `resolveExcelSheetNames(names)`             | Нормализует ограничения Excel (31 символ, forbidden chars) и делает имена уникальными.                               |
+| `resolveExcelCellStyleFromState(state)`     | Преобразует `State` в базовый цвет текста Excel.                                                                     |
+
+### Экспорт подготовленной таблицы
+
+`TableExcelColumnDescriptor` связывает generic Excel column с OData type/role и необязательным `formattersPipeline`. Используйте `createTableExcelColumn(descriptor)` для получения типизированного столбца, затем передавайте значения строк без предварительного UI-форматирования.
+
+| API                                                            | Назначение                                                                        |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `resolveTableExcelColumnType(descriptor)`                      | Выбирает `String`/`Number`/`Date`/`Boolean` по OData metadata и роли.             |
+| `createTableExcelColumn(descriptor)`                           | Создаёт `ExcelColumn` с Excel-маской числа/даты из published formatter contracts. |
+| `downloadResolvedExcelTable({ fileName, table, autoFilter? })` | Скачивает одну уже подготовленную таблицу.                                        |
+| `downloadResolvedExcelWorkbook({ fileName, sheets })`          | Скачивает несколько `ResolvedExcelTable` как листы книги.                         |
+
+Не передавайте в `rows` отформатированные через `Intl` строки для числовых и date-столбцов: Excel потеряет сортировку, формулы и формат. Строки создавайте только для действительно текстовых значений.
+
+## Ограничения
+
+- Все три entrypoint ориентированы на DOM/browser; не вызывайте их в server-only коде.
+- MIME по имени/сигнатуре не является проверкой безопасности содержимого. Сервер обязан валидировать загружаемые файлы повторно.
+- `download*` имеет пользовательский side effect. Вызывайте его из event handler, а не из render/effect при монтировании.

package/src/docs/formatters-runtime.mdx

@@ -0,0 +1,455 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/Formatters Runtime" />
+
+# Runtime форматтеров: pipeline, row-based и value state
+
+Эта страница описывает конфигурируемый runtime из
+`@ryuzaki13/react-foundation-lib/formatters`. Он предназначен для host-кода,
+который хранит сериализуемую настройку отображения, а затем компилирует её для
+ячейки таблицы, дерева или другого набора данных. Конфигурация и runtime —
+разные границы: в конфигурации нет функций, а скомпилированные executors нельзя
+сохранять в JSON, query cache или передавать между runtime-контекстами.
+
+```ts
+import {
+	compileFormattersPipelineExecutor,
+	formatPipelineDisplayValue,
+	validateFormattersPipelineConfig
+} from "@ryuzaki13/react-foundation-lib/formatters";
+
+import type {
+	FormattersPipelineConfig,
+	FormattersPipelineRuntimeField,
+	RowBasedFormatterDefinition,
+	ThresholdValueStateResolverConfig
+} from "@ryuzaki13/react-foundation-lib/formatters";
+```
+
+## Модель данных и жизненный цикл
+
+`FormattersPipelineConfig` имеет фиксированную версию `1` и содержит хотя бы
+один источник плана:
+
+```ts
+type FormattersPipelineConfig = {
+	version: 1;
+	graph?: FormattersPipelineGraph;
+	plan?: FormattersPipelinePlan;
+};
+```
+
+| Представление                    | Для чего хранится               | Содержимое                                                                                          |
+| -------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `graph`                          | Редактор настройки              | Узлы, рёбра и необязательный `viewport`. Граф обязан быть линейным от `source` к `sink`.            |
+| `plan`                           | Быстрое выполнение              | Массив последовательных шагов без координат. Если он валиден, у него приоритет над `graph`.         |
+| `FormattersPipelineExecutor`     | Только runtime                  | Функция `execute` и флаги. Появляется после компиляции, не сериализуется.                           |
+| `FormattersPipelineRuntimeField` | Construction-stage объекта поля | Содержит пользовательский конфиг и может получить `formulaExecutor` / `formattersPipelineExecutor`. |
+
+Безопасный порядок работы:
+
+1. Создать или восстановить конфиг как обычные JSON-данные.
+2. Для `rowBasedOverride` с `mode: "formula"` один раз настроить реестр
+   host-формул **до** validation и compilation.
+3. Проверить `validateFormattersPipelineConfig`; неизвестный или устаревший
+   конфиг не компилировать.
+4. На явной границе восстановления можно вызвать
+   `normalizeFormattersPipelineConfig` и положить полученную независимую копию
+   в модель.
+5. В construction-stage скомпилировать поле или карту полей.
+6. При отрисовке вызвать `formatPipelineDisplayValue` либо `executor.execute`.
+
+Не нормализуйте draft при каждом вводе. `clone…` создаёт независимую копию, а
+`normalize…` — проверяет внешнее `unknown` значение и допустим только на
+явной границе восстановления/сохранения конфигурации.
+
+## Минимальный сериализуемый pipeline
+
+```ts
+import {
+	compileFormattersPipelineRuntime,
+	formatPipelineDisplayValue,
+	validateFormattersPipelineConfig
+} from "@ryuzaki13/react-foundation-lib/formatters";
+
+import type { FormattersPipelineConfig } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const config = {
+	version: 1,
+	plan: {
+		steps: [
+			{
+				id: "pad-code",
+				type: "normalizeLeadingZeros",
+				config: { fixed: 5 }
+			},
+			{
+				id: "score-state",
+				type: "resolveValueState",
+				config: {
+					resolver: {
+						kind: "threshold",
+						thresholds: [60, 95],
+						states: ["warning", "success", "error"]
+					},
+					icon: { enabled: true, showValue: true, position: "left" }
+				}
+			},
+			{
+				id: "typed-value",
+				type: "typedValueFormat",
+				config: { numberPresetName: "decimal-2" }
+			}
+		]
+	}
+} satisfies FormattersPipelineConfig;
+
+const validation = validateFormattersPipelineConfig(config);
+if (!validation.ok) {
+	throw new Error(validation.errors.map((item) => item.message).join("\n"));
+}
+
+const field = {
+	id: "score",
+	role: "measure",
+	type: "decimal",
+	formattersPipeline: config
+};
+
+// Важно: эта функция записывает executors в сам объект field.
+compileFormattersPipelineRuntime(field);
+
+const display = formatPipelineDisplayValue({
+	field,
+	rawValue: "63.4",
+	rowData: { score: "63.4" },
+	rowKind: "plain"
+});
+
+// display.value === "63,40"
+// display.state === "success"
+```
+
+## Шаги pipeline
+
+`FormattersPipelineFormatterId` допускает только четыре значения.
+
+| Шаг                     | Конфигурация                                | Выполнение и fallback                                         |
+| ----------------------- | ------------------------------------------- | ------------------------------------------------------------- |
+| `normalizeLeadingZeros` | `{ fixed?: number }`                        | Передаёт текущее значение в `normalizeLeadingZeros`.          |
+| `rowBasedOverride`      | field- или formula-вариант ниже             | Подменяет текущее значение данными строки.                    |
+| `resolveValueState`     | fixed/threshold resolver и настройки иконки | Вычисляет `state`, `showIcon`, `showValue`, `iconPosition`.   |
+| `typedValueFormat`      | `{ numberPresetName?, datePresetName? }`    | Форматирует итог по OData-type поля: number, date или строка. |
+
+Ограничения валидатора:
+
+- В плане разрешён не более чем один шаг каждого вида.
+- `typedValueFormat` не может идти раньше `resolveValueState`.
+- У каждого шага должен быть непустой уникальный `id`.
+- Для threshold-resolver длина `states` обязана равняться
+  `thresholds.length + 1`.
+- `showValue: false` при выключенной иконке — warning: ячейка не покажет
+  значение.
+- В графе должны быть ровно один `source` и один `sink`; каждый путь должен
+  быть линейным, без циклов, разветвлений, оборванных и отключённых узлов.
+
+`FormattersPipelineExecutionContext` получает исходное `value`, `rowData`,
+`rowKind`, уровень/группировки и `columnId`. Новый код определяет семантику
+строки через `rowKind: "plain" | "tree" | "group" | "totals"` — поля
+`isGroupRow` и `isTotalsRow` в этом контексте оставлены только для
+совместимости.
+
+`executor.execute(ctx)` возвращает `FormattersPipelineExecutionResult`:
+`value`, `state`, опциональную `icon`, `showIcon`, `showValue`,
+`iconPosition`, `hasTypedValueFormat`.
+
+### rowBasedOverride
+
+```ts
+type FormattersPipelineRowBasedOverrideConfig =
+	| {
+			mode: "field";
+			fieldKey: string;
+			fallbackToRaw?: boolean;
+	  }
+	| {
+			mode: "formula";
+			formulaId: string;
+			dependencyIds?: string[];
+			fallbackToRaw?: boolean;
+	  };
+```
+
+| Режим     | Источник значения                  | Семантика по типу строки                                          |
+| --------- | ---------------------------------- | ----------------------------------------------------------------- |
+| `field`   | `rowData[fieldKey]`                | Работает для `plain`, `tree`, `group`; не применяется к `totals`. |
+| `formula` | `fn(context)` из row-based реестра | Работает для `plain`, `tree`, `group` и `totals`.                 |
+
+Если подмена возвращает `null`/`undefined`, `fallbackToRaw` по умолчанию
+сохраняет предыдущее значение. При `fallbackToRaw: false` это значение
+допускается как новый результат. Ошибка formula в executor не пробрасывается:
+при default fallback остаётся прежнее значение, а при `false` получается
+`undefined`.
+
+`dependencyIds` — упорядоченные ключи, которые formula читает по индексам.
+Их необходимо запросить вместе с основной строкой: для этого используйте
+`collectFormattersPipelineDependencyIds` или
+`collectRuntimeFieldDependencyIds` до построения query.
+
+## Реестр row-based формул
+
+В конфиге хранится только `formulaId`; реальная функция существует только в
+runtime host-приложения. Реестр глобален для экземпляра модуля, поэтому его
+надо установить один раз при bootstrap, до первого вызова валидации или
+компиляции pipeline с формульным шагом.
+
+```ts
+import { configureRowBasedFormatterRegistry, createRowBasedFormatterRegistry } from "@ryuzaki13/react-foundation-lib/formatters";
+
+configureRowBasedFormatterRegistry(
+	createRowBasedFormatterRegistry([
+		{
+			id: "sum-dependencies",
+			name: "Сумма зависимостей",
+			description: "Складывает первые два поля строки.",
+			fn: ({ num }) => num(0) + num(1)
+		}
+	])
+);
+```
+
+| API                                            | Контракт                                                                                 |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `createRowBasedFormatterRegistry(definitions)` | Возвращает immutable registry. Бросает `Error` для пустого `id` или дубликата.           |
+| `configureRowBasedFormatterRegistry(registry)` | Подменяет активный module-scoped реестр. Не вызывайте повторно в обычном rendering flow. |
+| `getRowBasedFormatterList()`                   | Список доступных host-формул.                                                            |
+| `getRowBasedFormatterById(id)`                 | Формула или `undefined` для пустого/неизвестного id.                                     |
+| `createRowBasedFormatterContext(args)`         | Создаёт контекст для прямого запуска formula или теста.                                  |
+
+`RowBasedFormatterDefinition` содержит `id`, `name`, `description`,
+`fn`. `RowBasedFormatterContext` содержит `rowData`, `rawValue`, `columnId`
+и методы:
+
+| Метод          | Результат                                                                   |
+| -------------- | --------------------------------------------------------------------------- |
+| `key(index)`   | ID зависимости или `undefined` для некорректного/вне диапазона индекса.     |
+| `value(index)` | Значение `rowData` зависимости или `undefined`.                             |
+| `num(index)`   | `parseNumber` значения зависимости; при отсутствии/невалидном значении `0`. |
+
+Формула должна быть синхронной и не должна полагаться на DOM, React state или
+неявные внешние данные. Валидация запускает её на тестовых положительных и
+отрицательных значениях, чтобы обнаружить недостающие/неиспользуемые
+`dependencyIds` и потенциальную runtime-ошибку. Это диагностический прогон, а
+не гарантия корректности для всех данных.
+
+## Проверка, нормализация, копирование и новые ID
+
+| API                                                                                                                              | Когда вызывать                                                       | Результат                                                                                                                   |
+| -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `validateFormattersPipelinePlan(plan)`                                                                                           | Перед сохранением/компиляцией готового линейного плана.              | `FormattersPipelineValidationResult` с `ok`, `errors`, `warnings` и безопасным `plan` только при успехе.                    |
+| `validateFormattersPipelineGraph(graph)`                                                                                         | Для editor graph.                                                    | Проверяет структуру и строит линейный `plan`.                                                                               |
+| `validateFormattersPipelineConfig(config)`                                                                                       | Основная проверка конфигурации.                                      | Валидный `plan` имеет приоритет; если он невалиден и есть `graph`, выполняется попытка построения по графу с warning.       |
+| `normalizeFormattersPipelineConfig(unknownValue)`                                                                                | На внешней restore/save boundary.                                    | Возвращает валидный независимый `FormattersPipelineConfig` или `undefined`; не исправляет невалидные данные «по умолчанию». |
+| `cloneFormattersPipelineConfig(config)`                                                                                          | Для literal draft, setter или безопасного переноса конфигурации.     | Глубокая независимая копия или `undefined`; не валидирует и не нормализует.                                                 |
+| `cloneTypedValueFormatConfig`, `cloneNormalizeLeadingZerosConfig`, `cloneRowBasedOverrideConfig`, `cloneResolveValueStateConfig` | Для узких UI-операций редактора.                                     | Копия соответствующего вложенного конфига.                                                                                  |
+| `cloneFormatterPipelinePlanStep`, `cloneFormatterPipelinePlanStepToNode`                                                         | При преобразовании plan-шага в editor node.                          | Независимый step или node с заданной позицией.                                                                              |
+| `rekeyFormattersPipelineConfig(config, idFactory?)`                                                                              | Только при создании независимой копии для нового редактора/сущности. | Переиздаёт технические id пользовательских step/node и рёбер; `source`/`sink` сохраняют id. По умолчанию использует UUID.   |
+
+`FormattersPipelineValidationMessage` содержит машинный `code` и русское
+`message`; не распознавайте проблему по тексту сообщения. Для UI удобно
+показывать `errors`, а `warnings` отображать как необязательные рекомендации.
+
+Каталог узлов можно получить без дублирования строк интерфейса:
+
+```ts
+import { getFormattersPipelineDefinitionById, getFormattersPipelineDefinitions } from "@ryuzaki13/react-foundation-lib/formatters";
+
+getFormattersPipelineDefinitions();
+getFormattersPipelineDefinitionById("typedValueFormat");
+```
+
+`getFormattersPipelineDefinitions()` и
+`getFormattersPipelineDefinitionById(id)` — публичный способ получить
+readonly-каталог и описание конкретного вида форматтера.
+
+## Компиляция и отображение
+
+### Низкоуровневый executor
+
+```ts
+import { compileFormattersPipelineExecutor, formatTypedCellValue } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const compiled = compileFormattersPipelineExecutor({
+	config,
+	column: { role: "measure", type: "decimal" }
+});
+
+if (compiled.ok) {
+	compiled.executor.execute({
+		value: 12.5,
+		rowData: {},
+		rowKind: "plain",
+		isGroupRow: false,
+		isTotalsRow: false,
+		rowLevel: 0,
+		groupingIds: [],
+		columnId: "amount"
+	});
+}
+
+formatTypedCellValue(12.5, { role: "measure", type: "decimal" });
+// "12,5" — default number preset "decimal"
+```
+
+`compileFormattersPipelineExecutor` повторно валидирует config и возвращает
+либо `{ ok: true, executor }`, либо `{ ok: false, reason }`. Причины ошибки:
+`"pipeline_invalid"` и `"row_based_formula_not_found"`. В последнем случае
+надо исправить порядок bootstrap и зарегистрировать formula, а не подменять
+её локальной функцией в сериализуемом конфиге.
+
+`formatTypedCellValue(value, column, config?)` работает и без pipeline:
+
+| Базовый OData-type    | Поведение                                               |
+| --------------------- | ------------------------------------------------------- |
+| Число                 | `formatNumber`; default preset `decimal`.               |
+| Дата                  | `parseDate`, затем `formatDate`; default preset `date`. |
+| Остальное             | `toSafeString`.                                         |
+| Небезопасное значение | Пустая строка.                                          |
+
+Для прямого вызова неизвестное имя number/date-пресета заменяется default
+пресетом. В полноценном pipeline валидатор отдельно делает неизвестный или
+пустой `numberPresetName` ошибкой; неизвестный `datePresetName` в runtime
+безопасно даёт preset `date`.
+
+### Runtime полей
+
+| API                                                  | Важное свойство                                                                                                                                                                    |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compileFormattersPipelineRuntime(field)`            | Компилирует `formulaExecutor` и `formattersPipelineExecutor` и **мутирует переданный `field`**. Допустим только до помещения поля в readonly snapshot, memoized context или cache. |
+| `compileFormattersPipelineRuntimeFields(fieldsById)` | Компилирует каждое существующее поле; также не пересобирает и не копирует сами поля.                                                                                               |
+| `formatPipelineDisplayValue(args)`                   | Возвращает `FormattersPipelineDisplayValue`, пригодный для UI: значение, state, настройки иконки и `overflowTooltip`.                                                              |
+
+Перед pipeline `formatPipelineDisplayValue` при необходимости выполняет
+`field.formulaExecutor`. Если формула отсутствует/ошиблась, `purelyDerived`
+поле отображается пустым, а обычное поле возвращается к `rawValue`. После
+pipeline fallback-форматирование по типу применяется автоматически, если в
+плане не было `typedValueFormat`. `emptyWhenZero` скрывает нулевой результат
+исходной формулы/значения как пустую строку.
+
+`formulaId` и `formulaDependencies` относятся к реестру формул host-проекта:
+необходимая формула должна быть уже доступна до `compile…Runtime`, а её
+зависимости нужно включить в данные строки.
+
+## Планирование зависимостей данных
+
+```ts
+import { collectFormattersPipelineDependencyIds, collectRuntimeFieldDependencyIds } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const dependencies = collectFormattersPipelineDependencyIds(config);
+// Только fieldKey/dependencyIds из rowBasedOverride.
+
+const runtimePlan = collectRuntimeFieldDependencyIds(["score"], {
+	score: {
+		formattersPipeline: config,
+		cellRenderer: { bindings: { caption: "score-label" } }
+	},
+	"score-label": {}
+});
+// runtimePlan.requiredColumnIds / runtimePlan.missingColumnIds
+```
+
+`collectFormattersPipelineDependencyIds(config)` возвращает только уникальные
+IDs из valid `rowBasedOverride` в порядке первого появления.
+`collectRuntimeFieldDependencyIds(fieldIds, fieldsById)` дополнительно
+учитывает `cellRenderer.bindings`, отделяя известные IDs в
+`requiredColumnIds` от отсутствующих в `missingColumnIds`. Функции не делают
+query сами: host обязан добавить `requiredColumnIds` в запрос до исполнения
+pipeline.
+
+## Value state
+
+`State` допускает `""`, `"none"`, `"information"`, `"success"`,
+`"warning"`, `"error"`. Resolver сопоставляет значению одно из этих состояний
+и хранится в global registry данного module instance.
+
+### Fixed resolver
+
+```ts
+import { createFixedResolver, registerFixedResolver, resolveValueState } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const resolverId = registerFixedResolver({
+	entries: { A: "success", B: "warning", C: "error" },
+	fallbackState: "none"
+});
+
+resolveValueState(resolverId, "B"); // "warning"
+
+const resolve = createFixedResolver({ entries: { A: "success" } });
+resolve("A"); // "success"
+```
+
+`FixedValueStateResolverConfig` содержит `entries: Record<string, State>` и
+необязательный `fallbackState` (по умолчанию `"none"`). Сопоставление точное
+по `String(value)`; `null` и `undefined` сразу дают fallback. Идентичные по
+содержимому конфигурации дедуплицируются, поэтому регистрация возвращает один
+и тот же id.
+
+### Threshold resolver
+
+```ts
+import { createThresholdResolver, registerThresholdResolver } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const resolve = createThresholdResolver({
+	thresholds: [{ value: 60, boundary: "lower" }, 95],
+	states: ["warning", "success", "error"],
+	invalidState: "none"
+});
+
+resolve(60); // "warning": boundary "lower" использует <=
+resolve(95); // "error": числовой threshold по умолчанию использует <
+```
+
+`ThresholdValueStateResolverConfig`:
+
+| Поле           | Правило                                                                                                                                                                                  |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `thresholds`   | Числа либо `{ value, boundary? }`; `boundary: "upper"` по умолчанию означает, что порог относится к верхнему сегменту (`<` для нижнего). `"lower"` включает его в нижний сегмент (`<=`). |
+| `states`       | Ровно `thresholds.length + 1` состояний в порядке диапазонов от меньших значений к большим. Иначе `create…`/`register…` бросит `Error`.                                                  |
+| `invalidState` | Результат для пустого, `NaN`, бесконечного или нечислового значения; default `"none"`.                                                                                                   |
+
+Пороги сортируются перед compilation, но массив `states` не переставляется.
+Передавайте `thresholds` сразу по возрастанию, чтобы соответствие сегментов и
+states было однозначным. Для дублирующихся порогов библиотека выводит
+`console.warn`, но продолжает работу.
+
+### Реестр и presentation helpers
+
+| API                                                                                                 | Поведение / side effect                                                                                              |
+| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `registerFixedResolver`, `registerThresholdResolver`                                                | Регистрируют конфигурационный resolver и возвращают его детерминированный короткий id.                               |
+| `createFixedResolver`, `createThresholdResolver`                                                    | Возвращают функцию resolver; также используют общий registry и дедупликацию.                                         |
+| `resolveValueState(id, value)`                                                                      | Возвращает `"none"`, если id не найден.                                                                              |
+| `getValueStateResolver(id)`, `getValueStateResolverIds()`                                           | Читают resolver или список ids.                                                                                      |
+| `registerResolver(canonicalKey, compileFunction)`, `findResolverByCanonicalKey`, `computeShortHash` | Низкоуровневый API для специальных host-резолверов. `compileFunction` — runtime-функция, её нельзя хранить в config. |
+| `resetValueStateResolvers()`                                                                        | Очищает global registry. Только для изолированных тестов: сбросит resolvers, созданные скомпилированными pipeline.   |
+| `DEFAULT_VALUE_STATES`                                                                              | Readonly список presentation-состояний без пустого значения.                                                         |
+| `VALUE_STATE_COLOR_TOKENS`                                                                          | Соответствие `State` CSS token. Не меняет DOM и не подключает стили.                                                 |
+| `resolveValueStateClassName(state, fallbackClassName?)`                                             | Для `success` / `warning` / `error` / `information` возвращает `status…`; для остальных — fallback.                  |
+
+## Runtime-ограничения
+
+- Реестры row-based formatter-ов и value-state resolver-ов — module-scoped
+  mutable state. Инициализируйте их один раз до compilation и не меняйте во
+  время рендера.
+- Config должен оставаться сериализуемым: IDs, строки, числа, массивы и
+  plain objects. Не сохраняйте `fn`, executor, `Map`, `Date`, React node или
+  registry в конфигурации.
+- `compileFormattersPipelineRuntime` меняет входной объект. Сначала создайте
+  обычный mutable construction object, затем скомпилируйте его и только после
+  этого публикуйте readonly snapshot.
+- `resetDatePresets`, `resetNumberPresets`, `resetValueStateResolvers` и
+  повторная настройка row-based registry предназначены для тестов/явно
+  изолированных окружений, а не для обычного пользовательского сценария.
+- Ошибки validation следует показывать владельцу конфигурации. Не
+  компилируйте невалидный config и не маскируйте missing formula пустой
+  локальной реализацией.