@ryuzaki13/react-foundation-ui 1.8.5 → 1.8.7

package/storybook-static/assets/README-BgeYwR6t.js

@@ -0,0 +1,347 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-CViB2sFm.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B8F5vBhs.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/Row-Based`}),`
+`,(0,c.jsx)(t.h1,{id:`row-based-форматтеры`,children:`Row-based форматтеры`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`rowBased`}),` — небольшой runtime-слой для формул, которые вычисляют отображаемое значение одной ячейки на основании других полей той же строки.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Он используется шагом `,(0,c.jsx)(t.code,{children:`rowBasedOverride`}),` в `,(0,c.jsx)(t.a,{href:`../pipeline/README.mdx`,children:`formatter pipeline`}),`. Сам модуль не содержит бизнес-формул: host-приложение создаёт их, собирает в реестр и один раз передаёт реестр библиотеке.`]}),`
+`,(0,c.jsx)(t.p,{children:`Все публичные значения импортируются из общего entrypoint:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	configureRowBasedFormatterRegistry,
+	createRowBasedFormatterContext,
+	createRowBasedFormatterRegistry,
+	getRowBasedFormatterById,
+	getRowBasedFormatterList,
+	type RowBasedFormatterContext,
+	type RowBasedFormatterDefinition,
+	type RowBasedFormatterFn,
+	type RowBasedFormatterRegistry
+} from "@ryuzaki13/react-foundation-lib/formatters";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Отдельного импорта `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/formatters/rowBased`}),` нет.`]}),`
+`,(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-ts`,children:`const rowData = {
+	plannedHours: "160",
+	actualHours: "144"
+};
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Таблица должна показать процент выполнения. Формула может прочитать зависимости по индексам и вычислить значение:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const completionPercent: RowBasedFormatterDefinition = {
+	id: "completion-percent",
+	name: "Процент выполнения",
+	description: "Вычисляет actual / planned * 100",
+	fn: (ctx) => {
+		const planned = ctx.num(0);
+		const actual = ctx.num(1);
+
+		return planned === 0 ? undefined : (actual / planned) * 100;
+	}
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Индексы `,(0,c.jsx)(t.code,{children:`0`}),` и `,(0,c.jsx)(t.code,{children:`1`}),` связываются с конкретными полями в конфигурации pipeline:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const dependencyIds = ["plannedHours", "actualHours"];
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Таким образом, одна и та же функция не привязана к конкретному имени поля. Порядок зависимостей является частью контракта формулы.`}),`
+`,(0,c.jsx)(t.h2,{id:`жизненный-цикл`,children:`Жизненный цикл`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`Host объявляет definitions
+        ↓
+createRowBasedFormatterRegistry(definitions)
+        ↓
+configureRowBasedFormatterRegistry(registry)
+        ↓
+валидация и компиляция formatter pipeline
+        ↓
+формула выполняется для конкретных строк
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Конфигурируйте реестр на старте приложения, до первой валидации или компиляции pipeline. Уже скомпилированный executor хранит найденную функцию; замена глобального реестра не переписывает существующие executors.`}),`
+`,(0,c.jsx)(t.h2,{id:`минимальная-настройка`,children:`Минимальная настройка`}),`
+`,(0,c.jsx)(t.h3,{id:`1-объявите-формулы`,children:`1. Объявите формулы`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import type { RowBasedFormatterDefinition } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const definitions: RowBasedFormatterDefinition[] = [
+	{
+		id: "sum-two-fields",
+		name: "Сумма двух полей",
+		description: "Складывает две выбранные числовые зависимости",
+		fn: (ctx) => ctx.num(0) + ctx.num(1)
+	},
+	{
+		id: "first-non-empty",
+		name: "Первое заполненное значение",
+		description: "Использует первую зависимость, затем вторую, затем raw value",
+		fn: (ctx) => ctx.value(0) ?? ctx.value(1) ?? ctx.rawValue
+	}
+];
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`2-создайте-и-установите-реестр`,children:`2. Создайте и установите реестр`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { configureRowBasedFormatterRegistry, createRowBasedFormatterRegistry } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const registry = createRowBasedFormatterRegistry(definitions);
+
+configureRowBasedFormatterRegistry(registry);
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Обычно это выполняется один раз в bootstrap-коде приложения.`}),`
+`,(0,c.jsx)(t.h3,{id:`3-сошлитесь-на-формулу-из-pipeline`,children:`3. Сошлитесь на формулу из pipeline`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import type { FormattersPipelineConfig } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const formattersPipeline: FormattersPipelineConfig = {
+	version: 1,
+	plan: {
+		steps: [
+			{
+				id: "override-1",
+				type: "rowBasedOverride",
+				config: {
+					mode: "formula",
+					formulaId: "sum-two-fields",
+					dependencyIds: ["planned", "actual"],
+					fallbackToRaw: true
+				}
+			}
+		]
+	}
+};
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`контекст-формулы`,children:`Контекст формулы`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type RowBasedFormatterContext = {
+	rowData: Record<string, unknown>;
+	rawValue: unknown;
+	columnId: string;
+	key: (index: number) => string | undefined;
+	value: (index: number) => unknown;
+	num: (index: number) => number;
+};
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`ctxkeyindex`,children:(0,c.jsx)(t.code,{children:`ctx.key(index)`})}),`
+`,(0,c.jsx)(t.p,{children:`Возвращает имя зависимости по индексу:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// dependencyIds = ["planned", "actual"]
+ctx.key(0); // "planned"
+ctx.key(1); // "actual"
+ctx.key(2); // undefined
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Индекс должен быть целым неотрицательным числом. `,(0,c.jsx)(t.code,{children:`-1`}),`, `,(0,c.jsx)(t.code,{children:`1.5`}),`, `,(0,c.jsx)(t.code,{children:`NaN`}),` и индекс за границами массива возвращают `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ctxvalueindex`,children:(0,c.jsx)(t.code,{children:`ctx.value(index)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Находит ключ через `,(0,c.jsx)(t.code,{children:`ctx.key(index)`}),` и возвращает `,(0,c.jsx)(t.code,{children:`rowData[key]`}),` без преобразования:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// rowData.actual === "144"
+ctx.value(1); // "144"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если ключ отсутствует, пуст или выходит за границы, возвращается `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ctxnumindex`,children:(0,c.jsx)(t.code,{children:`ctx.num(index)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Читает зависимость и преобразует её функцией `,(0,c.jsx)(t.code,{children:`parseNumber`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`ctx.num(0); // 160
+ctx.num(1); // 144
+ctx.num(99); // 0
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Невалидное, пустое или отсутствующее значение превращается в `,(0,c.jsx)(t.code,{children:`0`}),`. Это удобно для сумм, но опасно, если `,(0,c.jsx)(t.code,{children:`0`}),` и «данных нет» имеют разный бизнес-смысл. В таком случае сначала используйте `,(0,c.jsx)(t.code,{children:`ctx.value(index)`}),` и самостоятельно проверьте значение.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ctxrawvalue`,children:(0,c.jsx)(t.code,{children:`ctx.rawValue`})}),`
+`,(0,c.jsx)(t.p,{children:`Исходное значение текущей ячейки до row-based подмены. Оно полезно как fallback:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`fn: (ctx) => ctx.value(0) ?? ctx.rawValue;
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`ctxrowdata`,children:(0,c.jsx)(t.code,{children:`ctx.rowData`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Вся строка как `,(0,c.jsx)(t.code,{children:`Record<string, unknown>`}),`. Предпочитайте индексные методы `,(0,c.jsx)(t.code,{children:`value`}),` и `,(0,c.jsx)(t.code,{children:`num`}),`, когда поле объявлено зависимостью pipeline: тогда dependency collector сможет добавить его в запрос, а validator — проверить формулу.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Прямой доступ к `,(0,c.jsx)(t.code,{children:`rowData.someField`}),` не отслеживается автоматически.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ctxcolumnid`,children:(0,c.jsx)(t.code,{children:`ctx.columnId`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Идентификатор форматируемой колонки. Позволяет общей формуле учитывать текущую колонку, но частые ветвления по `,(0,c.jsx)(t.code,{children:`columnId`}),` могут быть признаком того, что лучше создать несколько небольших формул.`]}),`
+`,(0,c.jsx)(t.h2,{id:`createrowbasedformattercontextargs`,children:(0,c.jsx)(t.code,{children:`createRowBasedFormatterContext(args)`})}),`
+`,(0,c.jsx)(t.p,{children:`Создаёт контекст вручную. В обычном runtime это делает pipeline, но функция полезна для тестов или другого адаптера.`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const context = createRowBasedFormatterContext({
+	rowData: { price: "12,5", count: "4" },
+	rawValue: undefined,
+	columnId: "total",
+	keys: ["price", "count"]
+});
+
+context.value(0); // "12,5"
+context.num(0); // 12.5
+context.num(1); // 4
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Массив `,(0,c.jsx)(t.code,{children:`keys`}),` копируется при создании контекста. Последующее изменение исходного массива не меняет сопоставление индексов внутри уже созданного контекста.`]}),`
+`,(0,c.jsx)(t.h3,{id:`инструментирование`,children:`Инструментирование`}),`
+`,(0,c.jsxs)(t.p,{children:[`Необязательное поле `,(0,c.jsx)(t.code,{children:`instrumentation`}),` позволяет отследить обращения к индексам:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const readIndexes: number[] = [];
+const invalidIndexes: number[] = [];
+
+const context = createRowBasedFormatterContext({
+	rowData: { amount: 10 },
+	rawValue: 10,
+	columnId: "amount",
+	keys: ["amount"],
+	instrumentation: {
+		onReadIndex: (index) => readIndexes.push(index),
+		onOutOfRangeIndex: (index) => invalidIndexes.push(index)
+	}
+});
+
+context.num(0);
+context.num(2);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`onReadIndex`}),` вызывается только для целого неотрицательного индекса, в том числе если он уже вышел за длину `,(0,c.jsx)(t.code,{children:`keys`}),`. `,(0,c.jsx)(t.code,{children:`onOutOfRangeIndex`}),` вызывается для любого недопустимого индекса.`]}),`
+`,(0,c.jsx)(t.p,{children:`Formatter pipeline использует этот механизм при валидации formula-режима.`}),`
+`,(0,c.jsx)(t.h2,{id:`реестр-формул`,children:`Реестр формул`}),`
+`,(0,c.jsx)(t.h3,{id:`createrowbasedformatterregistrydefinitions`,children:(0,c.jsx)(t.code,{children:`createRowBasedFormatterRegistry(definitions)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function createRowBasedFormatterRegistry(definitions: readonly RowBasedFormatterDefinition[]): RowBasedFormatterRegistry;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Для каждого definition функция:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`обрезает пробелы вокруг `,(0,c.jsx)(t.code,{children:`id`}),`, `,(0,c.jsx)(t.code,{children:`name`}),` и `,(0,c.jsx)(t.code,{children:`description`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`запрещает пустой `,(0,c.jsx)(t.code,{children:`id`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`запрещает повторяющийся `,(0,c.jsx)(t.code,{children:`id`}),` после обрезки;`]}),`
+`,(0,c.jsx)(t.li,{children:`создаёт поверхностно замороженный definition;`}),`
+`,(0,c.jsxs)(t.li,{children:[`сохраняет порядок входного массива в `,(0,c.jsx)(t.code,{children:`registry.list`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const registry = createRowBasedFormatterRegistry([
+	{
+		id: "  total  ",
+		name: "  Итого  ",
+		description: "  Сумма  ",
+		fn: (ctx) => ctx.num(0) + ctx.num(1)
+	}
+]);
+
+registry.list[0].id; // "total"
+registry.list[0].name; // "Итого"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Ошибочные определения приводят к исключению:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`createRowBasedFormatterRegistry([{ id: " ", name: "", description: "", fn: () => 0 }]);
+// Error: Formula id ... не может быть пустым
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`createRowBasedFormatterRegistry([
+	{ id: "sum", name: "A", description: "", fn: () => 0 },
+	{ id: " sum ", name: "B", description: "", fn: () => 0 }
+]);
+// Error: дублирующийся formulaId ...
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Реестр и его список заморожены поверхностно. `,(0,c.jsx)(t.code,{children:`byId`}),` типизирован как `,(0,c.jsx)(t.code,{children:`ReadonlyMap`}),`; не приводите его обратно к изменяемому `,(0,c.jsx)(t.code,{children:`Map`}),` и не мутируйте внутренности вручную.`]}),`
+`,(0,c.jsx)(t.h3,{id:`configurerowbasedformatterregistryregistry`,children:(0,c.jsx)(t.code,{children:`configureRowBasedFormatterRegistry(registry)`})}),`
+`,(0,c.jsx)(t.p,{children:`Заменяет текущий глобальный реестр модуля:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`configureRowBasedFormatterRegistry(registry);
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Функция ничего не возвращает. Это глобальная конфигурация в пределах загруженного экземпляра модуля, поэтому:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`вызывайте её централизованно;`}),`
+`,(0,c.jsx)(t.li,{children:`завершайте конфигурацию до компиляции pipeline;`}),`
+`,(0,c.jsx)(t.li,{children:`не переключайте реестры для отдельных компонентов во время рендера;`}),`
+`,(0,c.jsxs)(t.li,{children:[`в тестах явно устанавливайте нужный реестр в `,(0,c.jsx)(t.code,{children:`beforeEach`}),`, если тесты влияют друг на друга.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h3,{id:`getrowbasedformatterlist`,children:(0,c.jsx)(t.code,{children:`getRowBasedFormatterList()`})}),`
+`,(0,c.jsx)(t.p,{children:`Возвращает список definitions в порядке регистрации. Подходит для select/listbox редактора pipeline:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const options = getRowBasedFormatterList().map((definition) => ({
+	value: definition.id,
+	label: definition.name
+}));
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Возвращается сам read-only список реестра, а не новая копия.`}),`
+`,(0,c.jsx)(t.h3,{id:`getrowbasedformatterbyidformulaid`,children:(0,c.jsx)(t.code,{children:`getRowBasedFormatterById(formulaId)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Обрезает пробелы вокруг id и возвращает definition либо `,(0,c.jsx)(t.code,{children:`undefined`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`getRowBasedFormatterById(" sum-two-fields "); // definition
+getRowBasedFormatterById(""); // undefined
+getRowBasedFormatterById(undefined); // undefined
+getRowBasedFormatterById("unknown"); // undefined
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`как-formula-режим-работает-в-pipeline`,children:`Как formula-режим работает в pipeline`}),`
+`,(0,c.jsx)(t.p,{children:`Для шага:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`{
+	id: "override",
+	type: "rowBasedOverride",
+	config: {
+		mode: "formula",
+		formulaId: "completion-percent",
+		dependencyIds: ["plannedHours", "actualHours"],
+		fallbackToRaw: true
+	}
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`runtime выполняет следующие действия:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`находит formula definition по `,(0,c.jsx)(t.code,{children:`formulaId`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`создаёт контекст, где `,(0,c.jsx)(t.code,{children:`dependencyIds`}),` становятся индексными `,(0,c.jsx)(t.code,{children:`keys`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`передаёт текущее значение pipeline как `,(0,c.jsx)(t.code,{children:`rawValue`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`вызывает `,(0,c.jsx)(t.code,{children:`definition.fn(context)`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`использует результат как следующее значение pipeline.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Если функция вернула `,(0,c.jsx)(t.code,{children:`null`}),` или `,(0,c.jsx)(t.code,{children:`undefined`}),`:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`при `,(0,c.jsx)(t.code,{children:`fallbackToRaw: true`}),` или без этого поля сохраняется предыдущее значение;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`при `,(0,c.jsx)(t.code,{children:`fallbackToRaw: false`}),` следующим значением становится `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Если функция выбросила ошибку, действует та же политика fallback.`}),`
+`,(0,c.jsxs)(t.p,{children:[`В отличие от field-режима, formula-режим выполняется и для totals-строк. Подробности описаны в `,(0,c.jsx)(t.a,{href:`../pipeline/README.mdx#%D1%88%D0%B0%D0%B3-rowbasedoverride`,children:`README pipeline`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`требования-к-функциям`,children:`Требования к функциям`}),`
+`,(0,c.jsx)(t.h3,{id:`формула-должна-быть-чистой`,children:`Формула должна быть чистой`}),`
+`,(0,c.jsx)(t.p,{children:`Pipeline validator запускает формулу на синтетических данных как минимум два раза — с положительными и отрицательными зависимостями. Поэтому функция не должна:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`отправлять запросы;`}),`
+`,(0,c.jsx)(t.li,{children:`изменять store;`}),`
+`,(0,c.jsx)(t.li,{children:`писать в DOM;`}),`
+`,(0,c.jsxs)(t.li,{children:[`менять `,(0,c.jsx)(t.code,{children:`rowData`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`зависеть от случайности или текущего времени;`}),`
+`,(0,c.jsx)(t.li,{children:`накапливать внешнее состояние.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Хорошая формула вычисляет и возвращает результат только из `,(0,c.jsx)(t.code,{children:`ctx`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const safeFormula: RowBasedFormatterFn = (ctx) => {
+	const total = ctx.num(0);
+	const completed = ctx.num(1);
+
+	return total > 0 ? completed / total : undefined;
+};
+`})}),`
+`,(0,c.jsx)(t.h3,{id:`формула-должна-быть-синхронной`,children:`Формула должна быть синхронной`}),`
+`,(0,c.jsxs)(t.p,{children:[`Тип результата — `,(0,c.jsx)(t.code,{children:`unknown`}),`, но runtime не ожидает `,(0,c.jsx)(t.code,{children:`Promise`}),`. `,(0,c.jsx)(t.code,{children:`async`}),`-функция вернёт Promise как отображаемое значение и не выполнит ожидаемое вычисление.`]}),`
+`,(0,c.jsx)(t.h3,{id:`обрабатывайте-деление-на-ноль-и-отсутствующие-данные`,children:`Обрабатывайте деление на ноль и отсутствующие данные`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`ctx.num()`}),` возвращает `,(0,c.jsx)(t.code,{children:`0`}),` для невалидных значений. Явно решите, что означает ноль в вашей формуле.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`fn: (ctx) => {
+	const denominatorRaw = ctx.value(0);
+	if (denominatorRaw == null || denominatorRaw === "") return undefined;
+
+	const denominator = ctx.num(0);
+	return denominator === 0 ? undefined : ctx.num(1) / denominator;
+};
+`})}),`
+`,(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-ts`,children:`import { createRowBasedFormatterContext } from "@ryuzaki13/react-foundation-lib/formatters";
+
+const context = createRowBasedFormatterContext({
+	rowData: {
+		plannedHours: "160",
+		actualHours: "144"
+	},
+	rawValue: undefined,
+	columnId: "completion",
+	keys: ["plannedHours", "actualHours"]
+});
+
+const result = completionPercent.fn(context);
+// result === 90
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Проверяйте как минимум:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`обычные значения;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`null`}),`, `,(0,c.jsx)(t.code,{children:`undefined`}),` и пустые строки;`]}),`
+`,(0,c.jsx)(t.li,{children:`нули и отрицательные числа;`}),`
+`,(0,c.jsx)(t.li,{children:`ошибочный или отсутствующий dependency;`}),`
+`,(0,c.jsxs)(t.li,{children:[`порядок `,(0,c.jsx)(t.code,{children:`dependencyIds`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`fallback к `,(0,c.jsx)(t.code,{children:`rawValue`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`настроить-реестр-после-компиляции-pipeline`,children:`Настроить реестр после компиляции pipeline`}),`
+`,(0,c.jsxs)(t.p,{children:[`Validator не найдёт `,(0,c.jsx)(t.code,{children:`formulaId`}),`, а executor может быть скомпилирован как невалидный. Конфигурируйте реестр на старте приложения.`]}),`
+`,(0,c.jsx)(t.h3,{id:`поменять-порядок-зависимостей`,children:`Поменять порядок зависимостей`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Формула ожидает [planned, actual]
+fn: (ctx) => ctx.num(1) / ctx.num(0);
+
+// Но конфиг передал [actual, planned] — результат изменится.
+dependencyIds: ["actual", "planned"];
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Документируйте ожидаемый порядок в `,(0,c.jsx)(t.code,{children:`description`}),` и тестах.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`читать-undeclared-поле-через-rowdata`,children:[`Читать undeclared поле через `,(0,c.jsx)(t.code,{children:`rowData`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Dependency collector видит `,(0,c.jsx)(t.code,{children:`dependencyIds`}),`, но не анализирует тело JavaScript-функции. Поле, прочитанное только через `,(0,c.jsx)(t.code,{children:`ctx.rowData.hiddenField`}),`, может не попасть в серверный query.`]}),`
+`,(0,c.jsx)(t.h3,{id:`делать-формулу-с-побочным-эффектом`,children:`Делать формулу с побочным эффектом`}),`
+`,(0,c.jsx)(t.p,{children:`Она может выполниться при валидации, а затем много раз для строк таблицы. Побочный эффект станет непредсказуемым и дорогим.`}),`
+`,(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:`API`}),(0,c.jsx)(t.th,{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:`createRowBasedFormatterContext`})}),(0,c.jsx)(t.td,{children:`Создать индексный контекст строки`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`RowBasedFormatterContext`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createRowBasedFormatterRegistry`})}),(0,c.jsx)(t.td,{children:`Нормализовать и собрать definitions`}),(0,c.jsxs)(t.td,{children:[`реестр; `,(0,c.jsx)(t.code,{children:`Error`}),` при пустом/повторном id`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`configureRowBasedFormatterRegistry`})}),(0,c.jsx)(t.td,{children:`Установить глобальный реестр`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`void`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`getRowBasedFormatterList`})}),(0,c.jsx)(t.td,{children:`Получить список для UI/диагностики`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`readonly RowBasedFormatterDefinition[]`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`getRowBasedFormatterById`})}),(0,c.jsx)(t.td,{children:`Найти definition по id`}),(0,c.jsxs)(t.td,{children:[`definition или `,(0,c.jsx)(t.code,{children:`undefined`})]})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Публичные TypeScript-типы: `,(0,c.jsx)(t.code,{children:`RowBasedFormatterContext`}),`, `,(0,c.jsx)(t.code,{children:`RowBasedFormatterContextInstrumentation`}),`, `,(0,c.jsx)(t.code,{children:`RowBasedFormatterFn`}),`, `,(0,c.jsx)(t.code,{children:`RowBasedFormatterDefinition`}),`, `,(0,c.jsx)(t.code,{children:`RowBasedFormatterRegistry`}),`.`]}),`
+`,(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:`../pipeline/README.mdx`,children:`Formatter pipeline`})}),`
+`,(0,c.jsx)(t.li,{children:(0,c.jsxs)(t.a,{href:`../number/README.mdx`,children:[`Числовые форматтеры и `,(0,c.jsx)(t.code,{children:`parseNumber`})]})}),`
+`]})]})}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};