@ryuzaki13/react-foundation-lib 2.26.0 → 2.28.0

package/dist/excel/index.js

@@ -1,6 +1,6 @@
 import { _n as e, c as t, l as n, ln as r, s as i, u as a, vn as o } from "../chunks/odata-service-tp2U5yIr.js";
 import { t as s, v as c } from "../chunks/validate-C8cQm_9m.js";
-import { p as l } from "../chunks/dom-Dbq_09-K.js";
+import { m as l } from "../chunks/dom-BK22UmgF.js";
 import { escapeXmlValue as u } from "../xml/index.js";
 import d from "write-excel-file/browser";
 //#region src/excel/excel.ts

package/dist/formatters/index.js

@@ -1,4 +1,4 @@
-import { $ as e, A as t, At as n, B as r, Bt as i, C as a, Ct as o, D as s, Dt as c, E as l, Et as u, F as d, Ft as f, G as p, Gt as m, H as h, Ht as g, I as _, It as v, J as y, Jt as b, K as x, Kt as S, L as C, Lt as w, M as T, Mt as E, N as D, Nt as O, O as k, Ot as A, P as j, Pt as M, Q as N, R as P, Rt as F, S as I, St as L, T as R, Tt as z, U as B, Ut as V, V as H, Vt as U, W, Wt as G, X as K, Y as q, Z as J, _ as Y, _t as X, a as Z, at as Q, b as $, bt as ee, c as te, ct as ne, d as re, dt as ie, et as ae, f as oe, ft as se, g as ce, gt as le, h as ue, ht as de, i as fe, it as pe, j as me, jt as he, k as ge, kt as _e, l as ve, lt as ye, m as be, mt as xe, n as Se, nt as Ce, o as we, ot as Te, p as Ee, pt as De, q as Oe, qt as ke, r as Ae, rt as je, s as Me, st as Ne, t as Pe, tt as Fe, u as Ie, ut as Le, v as Re, vt as ze, w as Be, wt as Ve, x as He, xt as Ue, y as We, yt as Ge, z as Ke, zt as qe } from "../chunks/formatters-DVqfmx3V.js";
+import { $ as e, A as t, At as n, B as r, Bt as i, C as a, Ct as o, D as s, Dt as c, E as l, Et as u, F as d, Ft as f, G as p, Gt as m, H as h, Ht as g, I as _, It as v, J as y, Jt as b, K as x, Kt as S, L as C, Lt as w, M as T, Mt as E, N as D, Nt as O, O as k, Ot as A, P as j, Pt as M, Q as N, R as P, Rt as F, S as I, St as L, T as R, Tt as z, U as B, Ut as V, V as H, Vt as U, W, Wt as G, X as K, Y as q, Z as J, _ as Y, _t as X, a as Z, at as Q, b as $, bt as ee, c as te, ct as ne, d as re, dt as ie, et as ae, f as oe, ft as se, g as ce, gt as le, h as ue, ht as de, i as fe, it as pe, j as me, jt as he, k as ge, kt as _e, l as ve, lt as ye, m as be, mt as xe, n as Se, nt as Ce, o as we, ot as Te, p as Ee, pt as De, q as Oe, qt as ke, r as Ae, rt as je, s as Me, st as Ne, t as Pe, tt as Fe, u as Ie, ut as Le, v as Re, vt as ze, w as Be, wt as Ve, x as He, xt as Ue, y as We, yt as Ge, z as Ke, zt as qe } from "../chunks/formatters-B_NcT2pe.js";
 import { _ as Je, b as Ye, g as Xe, v as Ze, x as Qe, y as $e } from "../chunks/array-D-_yMMUK.js";
 import { $t as et, An as tt, Bt as nt, Cn as rt, Dn as it, En as at, Fn as ot, Gt as st, Ht as ct, It as lt, Jt as ut, Kt as dt, Lt as ft, Mn as pt, Nn as mt, On as ht, Pn as gt, Qt as _t, Rt as vt, Sn as yt, Tn as bt, Ut as xt, Vt as St, Wt as Ct, Xt as wt, Yt as Tt, Zt as Et, _n as Dt, an as Ot, bn as kt, cn as At, dn as jt, en as Mt, fn as Nt, gn as Pt, hn as Ft, in as It, jn as Lt, kn as Rt, ln as zt, mn as Bt, nn as Vt, on as Ht, pn as Ut, qt as Wt, rn as Gt, sn as Kt, tn as qt, un as Jt, vn as Yt, wn as Xt, xn as Zt, yn as Qt, zt as $t } from "../chunks/odata-service-tp2U5yIr.js";
 import { _ as en, a as tn, b as nn, c as rn, d as an, f as on, g as sn, h as cn, i as ln, l as un, m as dn, n as fn, o as pn, p as mn, r as hn, s as gn, t as _n, u as vn, v as yn, x as bn, y as xn } from "../chunks/validate-C8cQm_9m.js";

package/dist/formulas/formatTableFormulaExpression.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Подставляет ID упорядоченных зависимостей в шаблон превью формулы.
+ *
+ * Незаданные позиции остаются в виде $n, чтобы редактор мог показывать неполный
+ * черновик. Подстановка однопроходная: ID сохраняются буквально, а полученный
+ * текст предназначен только для отображения и никогда не исполняется.
+ */
+export declare function formatTableFormulaExpression(expressionTemplate: string, dependencies: readonly string[]): string;
+//# sourceMappingURL=formatTableFormulaExpression.d.ts.map

package/dist/formulas/formatTableFormulaExpression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatTableFormulaExpression.d.ts","sourceRoot":"","sources":["../../src/formulas/formatTableFormulaExpression.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,kBAAkB,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAKhH"}

package/dist/formulas/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./execute";
+export * from "./formatTableFormulaExpression";
 export * from "./registry";
 export * from "./validate";
 export type * from "./types";

package/dist/formulas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formulas/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,mBAAmB,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formulas/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,mBAAmB,SAAS,CAAC"}

package/dist/formulas/index.js

@@ -109,14 +109,22 @@ function c(e) {
 	};
 }
 //#endregion
+//#region src/formulas/formatTableFormulaExpression.ts
+function l(e, t) {
+	return e.replace(/\$([0-9]+)/g, (e, n) => {
+		let r = t[Number(n)];
+		return r === void 0 || r === "" ? e : r;
+	});
+}
+//#endregion
 //#region src/formulas/validate.ts
-function l(e) {
+function u(e) {
 	return [...e].sort((e, t) => e - t);
 }
-function u(e, t) {
+function d(e, t) {
 	return e.reduce((e, n, r) => (e[n] = (r + 1) * t, e), {});
 }
-function d(e) {
+function f(e) {
 	let t = [], n = [], r = i(e.formulaId), a = [...e.dependencies ?? []], s = e.availableColumnIds ?? [];
 	if (!r) return t.push({
 		code: "formula_not_found",
@@ -131,10 +139,10 @@ function d(e) {
 			requiredDependencyCount: 0
 		}
 	};
-	let c = new Set(s), d = a.filter((e) => !c.has(e));
-	d.length > 0 && t.push({
+	let c = new Set(s), l = a.filter((e) => !c.has(e));
+	l.length > 0 && t.push({
 		code: "dependency_not_available",
-		message: `Не найдены среди доступных полей: ${d.join(", ")}.`
+		message: `Не найдены среди доступных полей: ${l.join(", ")}.`
 	});
 	let f = /* @__PURE__ */ new Set(), p = /* @__PURE__ */ new Set(), m = 0, h = (e) => {
 		try {
@@ -155,8 +163,8 @@ function d(e) {
 			m += 1;
 		}
 	};
-	h(u(a, 100)), h(u(a, -100));
-	let g = l(f), _ = g.length > 0 ? g[g.length - 1] + 1 : 0;
+	h(d(a, 100)), h(d(a, -100));
+	let g = u(f), _ = g.length > 0 ? g[g.length - 1] + 1 : 0;
 	p.size > 0 && t.push({
 		code: "dependency_index_out_of_range",
 		message: `Формула обращается к несуществующим индексам. Минимально требуется зависимостей: ${_}, выбрано: ${a.length}.`
@@ -185,6 +193,6 @@ function d(e) {
 	};
 }
 //#endregion
-export { s as compileTableFormula, n as configureTableFormulaRegistry, o as createTableFormulaContext, e as createTableFormulaRegistry, c as executeTableFormula, i as getTableFormulaById, r as getTableFormulaList, d as validateTableFormulaDependencies };
+export { s as compileTableFormula, n as configureTableFormulaRegistry, o as createTableFormulaContext, e as createTableFormulaRegistry, c as executeTableFormula, l as formatTableFormulaExpression, i as getTableFormulaById, r as getTableFormulaList, f as validateTableFormulaDependencies };
 
 //# sourceMappingURL=index.js.map

package/dist/formulas/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/formulas/registry.ts","../../src/formulas/execute.ts","../../src/formulas/validate.ts"],"sourcesContent":["import type { TableFormulaDefinition } from \"./types\";\n\nexport type TableFormulaRegistry = Readonly<{\n\tlist: readonly TableFormulaDefinition[];\n\tbyId: ReadonlyMap<string, TableFormulaDefinition>;\n}>;\n\nexport function createTableFormulaRegistry(definitions: readonly TableFormulaDefinition[]): TableFormulaRegistry {\n\tconst byId = new Map<string, TableFormulaDefinition>();\n\tconst list: TableFormulaDefinition[] = [];\n\n\tfor (const definition of definitions) {\n\t\tconst normalizedId = definition.id.trim();\n\t\tif (!normalizedId) {\n\t\t\tthrow new Error(\"Formula id не может быть пустым\");\n\t\t}\n\n\t\tif (byId.has(normalizedId)) {\n\t\t\tthrow new Error(`Найден дублирующийся formulaId: ${normalizedId}`);\n\t\t}\n\n\t\tconst normalizedDefinition: TableFormulaDefinition = Object.freeze({\n\t\t\t...definition,\n\t\t\tid: normalizedId,\n\t\t\tname: definition.name.trim(),\n\t\t\tdescription: definition.description.trim(),\n\t\t\tkeywords: definition.keywords ? [...definition.keywords] : undefined\n\t\t});\n\n\t\tbyId.set(normalizedId, normalizedDefinition);\n\t\tlist.push(normalizedDefinition);\n\t}\n\n\treturn Object.freeze({\n\t\tlist: Object.freeze(list),\n\t\tbyId\n\t});\n}\n\nlet tableFormulaRegistry = createTableFormulaRegistry([]);\n\n/**\n * Устанавливает реестр формул host-приложения для всех formula runtime API.\n *\n * Конфигурация выполняется composition root до первого чтения, валидации или\n * компиляции формулы. Библиотека намеренно не содержит прикладной каталог.\n */\nexport function configureTableFormulaRegistry(registry: TableFormulaRegistry): void {\n\ttableFormulaRegistry = registry;\n}\n\nexport function getTableFormulaList(): readonly TableFormulaDefinition[] {\n\treturn tableFormulaRegistry.list;\n}\n\nexport function getTableFormulaById(formulaId: string | undefined): TableFormulaDefinition | undefined {\n\tconst normalizedId = formulaId?.trim();\n\tif (!normalizedId) return undefined;\n\treturn tableFormulaRegistry.byId.get(normalizedId);\n}\n","import { getTableFormulaById } from \"./registry\";\n\nimport type { TableFormulaContext, TableFormulaRowData } from \"./types\";\n\ntype TableFormulaContextInstrumentation = {\n\tonReadIndex?: (index: number) => void;\n\tonOutOfRangeIndex?: (index: number) => void;\n};\n\nfunction toFiniteNumberOrZero(value: unknown): number {\n\tconst normalized = Number(value);\n\treturn Number.isFinite(normalized) ? normalized : 0;\n}\n\nexport function createTableFormulaContext(args: {\n\trowData: TableFormulaRowData;\n\tkeys?: readonly string[];\n\tinstrumentation?: TableFormulaContextInstrumentation;\n}): TableFormulaContext {\n\t// TODO: duplicate createRowBasedFormatterContext src\\shared\\lib\\formatters\\rowBased\\context.ts\n\tconst keys = [...(args.keys ?? [])];\n\n\tconst readKey = (index: number): string | undefined => {\n\t\tif (!Number.isInteger(index) || index < 0) {\n\t\t\targs.instrumentation?.onOutOfRangeIndex?.(index);\n\t\t\treturn undefined;\n\t\t}\n\n\t\targs.instrumentation?.onReadIndex?.(index);\n\n\t\tif (index >= keys.length) {\n\t\t\targs.instrumentation?.onOutOfRangeIndex?.(index);\n\t\t\treturn undefined;\n\t\t}\n\n\t\treturn keys[index];\n\t};\n\n\tconst readValue = (index: number): unknown => {\n\t\tconst key = readKey(index);\n\t\tif (!key) return undefined;\n\t\treturn args.rowData[key];\n\t};\n\n\treturn {\n\t\tkey: readKey,\n\t\tvalue: readValue,\n\t\tnum: (index) => toFiniteNumberOrZero(readValue(index))\n\t};\n}\n\nexport type TableFormulaExecutionResult =\n\t| {\n\t\t\tok: true;\n\t\t\tvalue: number;\n\t  }\n\t| {\n\t\t\tok: false;\n\t\t\treason: \"formula_not_found\" | \"invalid_result\" | \"runtime_error\";\n\t  };\n\nexport type TableFormulaCompiledExecutor = (rowData: TableFormulaRowData) => TableFormulaExecutionResult;\n\ntype CompileTableFormulaResult =\n\t| {\n\t\t\tok: true;\n\t\t\texecute: TableFormulaCompiledExecutor;\n\t  }\n\t| {\n\t\t\tok: false;\n\t\t\treason: \"formula_not_found\";\n\t  };\n\nexport function compileTableFormula(args: { formulaId: string | undefined; keys?: readonly string[] }): CompileTableFormulaResult {\n\tconst formula = getTableFormulaById(args.formulaId);\n\tif (!formula) {\n\t\treturn { ok: false, reason: \"formula_not_found\" };\n\t}\n\n\tconst keys = [...(args.keys ?? [])];\n\tlet rowDataRef: TableFormulaRowData = {};\n\tconst context: TableFormulaContext = {\n\t\tkey: (index) => (Number.isInteger(index) && index >= 0 && index < keys.length ? keys[index] : undefined),\n\t\tvalue: (index) => {\n\t\t\tif (!Number.isInteger(index) || index < 0 || index >= keys.length) return undefined;\n\t\t\tconst key = keys[index];\n\t\t\tif (!key) return undefined;\n\t\t\treturn rowDataRef[key];\n\t\t},\n\t\tnum: (index) => {\n\t\t\tif (!Number.isInteger(index) || index < 0 || index >= keys.length) return 0;\n\t\t\tconst key = keys[index];\n\t\t\tif (!key) return 0;\n\t\t\treturn toFiniteNumberOrZero(rowDataRef[key]);\n\t\t}\n\t};\n\n\treturn {\n\t\tok: true,\n\t\texecute: (rowData) => {\n\t\t\trowDataRef = rowData;\n\n\t\t\ttry {\n\t\t\t\tconst value = formula.fn(context);\n\t\t\t\tif (!Number.isFinite(value)) {\n\t\t\t\t\treturn { ok: false, reason: \"invalid_result\" };\n\t\t\t\t}\n\n\t\t\t\treturn { ok: true, value };\n\t\t\t} catch {\n\t\t\t\treturn { ok: false, reason: \"runtime_error\" };\n\t\t\t}\n\t\t}\n\t};\n}\n\nexport function executeTableFormula(args: {\n\tformulaId: string | undefined;\n\trowData: TableFormulaRowData;\n\tkeys?: readonly string[];\n}): TableFormulaExecutionResult {\n\tconst compiled = compileTableFormula({\n\t\tformulaId: args.formulaId,\n\t\tkeys: args.keys\n\t});\n\tif (!compiled.ok) {\n\t\treturn { ok: false, reason: compiled.reason };\n\t}\n\n\treturn compiled.execute(args.rowData);\n}\n","import { createTableFormulaContext } from \"./execute\";\nimport { getTableFormulaById } from \"./registry\";\n\ntype ValidationCode =\n\t| \"formula_not_found\"\n\t| \"dependency_index_out_of_range\"\n\t| \"dependency_not_available\"\n\t| \"unused_dependencies\"\n\t| \"formula_does_not_use_dependencies\"\n\t| \"formula_runtime_error\";\n\nexport interface TableFormulaValidationMessage {\n\tcode: ValidationCode;\n\tmessage: string;\n}\nexport interface TableFormulaDependenciesValidationResult {\n\tok: boolean;\n\terrors: TableFormulaValidationMessage[];\n\twarnings: TableFormulaValidationMessage[];\n\tusage: {\n\t\tusedDependencyIndexes: number[];\n\t\tusedDependencyIds: string[];\n\t\trequiredDependencyCount: number;\n\t};\n}\n\nfunction toSortedArray(items: Set<number>): number[] {\n\treturn [...items].sort((left, right) => left - right);\n}\n\nfunction createSampleRowData(dependencies: readonly string[], multiplier: number): Record<string, unknown> {\n\treturn dependencies.reduce<Record<string, unknown>>((acc, dependencyId, index) => {\n\t\tacc[dependencyId] = (index + 1) * multiplier;\n\t\treturn acc;\n\t}, {});\n}\n\nexport function validateTableFormulaDependencies(args: {\n\tformulaId: string | undefined;\n\tdependencies?: readonly string[];\n\tavailableColumnIds?: readonly string[];\n}): TableFormulaDependenciesValidationResult {\n\tconst errors: TableFormulaValidationMessage[] = [];\n\tconst warnings: TableFormulaValidationMessage[] = [];\n\n\tconst formula = getTableFormulaById(args.formulaId);\n\tconst dependencies = [...(args.dependencies ?? [])];\n\tconst availableColumnIds = args.availableColumnIds ?? [];\n\n\tif (!formula) {\n\t\terrors.push({\n\t\t\tcode: \"formula_not_found\",\n\t\t\tmessage: \"Формула не найдена в реестре.\"\n\t\t});\n\n\t\treturn {\n\t\t\tok: false,\n\t\t\terrors,\n\t\t\twarnings,\n\t\t\tusage: {\n\t\t\t\tusedDependencyIndexes: [],\n\t\t\t\tusedDependencyIds: [],\n\t\t\t\trequiredDependencyCount: 0\n\t\t\t}\n\t\t};\n\t}\n\n\tconst availableSet = new Set(availableColumnIds);\n\tconst missingDependencies = dependencies.filter((dependencyId) => !availableSet.has(dependencyId));\n\tif (missingDependencies.length > 0) {\n\t\terrors.push({\n\t\t\tcode: \"dependency_not_available\",\n\t\t\tmessage: `Не найдены среди доступных полей: ${missingDependencies.join(\", \")}.`\n\t\t});\n\t}\n\n\tconst usedIndexes = new Set<number>();\n\tconst outOfRangeIndexes = new Set<number>();\n\tlet runtimeErrorCount = 0;\n\n\tconst runValidationPass = (sampleRowData: Record<string, unknown>) => {\n\t\ttry {\n\t\t\tconst context = createTableFormulaContext({\n\t\t\t\trowData: sampleRowData,\n\t\t\t\tkeys: dependencies,\n\t\t\t\tinstrumentation: {\n\t\t\t\t\tonReadIndex: (index) => {\n\t\t\t\t\t\tusedIndexes.add(index);\n\t\t\t\t\t},\n\t\t\t\t\tonOutOfRangeIndex: (index) => {\n\t\t\t\t\t\toutOfRangeIndexes.add(index);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\t\tformula.fn(context);\n\t\t} catch {\n\t\t\truntimeErrorCount += 1;\n\t\t}\n\t};\n\n\t// Несколько прогонов повышают шанс увидеть обращения к индексам в разных ветках формулы.\n\trunValidationPass(createSampleRowData(dependencies, 100));\n\trunValidationPass(createSampleRowData(dependencies, -100));\n\n\tconst sortedUsedIndexes = toSortedArray(usedIndexes);\n\tconst requiredDependencyCount = sortedUsedIndexes.length > 0 ? sortedUsedIndexes[sortedUsedIndexes.length - 1] + 1 : 0;\n\n\tif (outOfRangeIndexes.size > 0) {\n\t\terrors.push({\n\t\t\tcode: \"dependency_index_out_of_range\",\n\t\t\tmessage: `Формула обращается к несуществующим индексам. Минимально требуется зависимостей: ${requiredDependencyCount}, выбрано: ${dependencies.length}.`\n\t\t});\n\t}\n\n\tif (sortedUsedIndexes.length === 0) {\n\t\twarnings.push({\n\t\t\tcode: \"formula_does_not_use_dependencies\",\n\t\t\tmessage: \"Формула не использует dependencies.\"\n\t\t});\n\t}\n\n\tconst unusedDependencies = dependencies.filter((_, index) => !usedIndexes.has(index));\n\tif (unusedDependencies.length > 0) {\n\t\twarnings.push({\n\t\t\tcode: \"unused_dependencies\",\n\t\t\tmessage: `Выбраны, но не используются формулой: ${unusedDependencies.join(\", \")}.`\n\t\t});\n\t}\n\n\tif (runtimeErrorCount > 0) {\n\t\twarnings.push({\n\t\t\tcode: \"formula_runtime_error\",\n\t\t\tmessage: \"На тестовых данных формула завершилась с ошибкой.\"\n\t\t});\n\t}\n\n\tconst usedDependencyIds = sortedUsedIndexes.map((index) => dependencies[index]).filter(Boolean);\n\n\treturn {\n\t\tok: errors.length === 0,\n\t\terrors,\n\t\twarnings,\n\t\tusage: {\n\t\t\tusedDependencyIndexes: sortedUsedIndexes,\n\t\t\tusedDependencyIds,\n\t\t\trequiredDependencyCount\n\t\t}\n\t};\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/formulas/registry.ts","../../src/formulas/execute.ts","../../src/formulas/formatTableFormulaExpression.ts","../../src/formulas/validate.ts"],"sourcesContent":["import type { TableFormulaDefinition } from \"./types\";\n\nexport type TableFormulaRegistry = Readonly<{\n\tlist: readonly TableFormulaDefinition[];\n\tbyId: ReadonlyMap<string, TableFormulaDefinition>;\n}>;\n\nexport function createTableFormulaRegistry(definitions: readonly TableFormulaDefinition[]): TableFormulaRegistry {\n\tconst byId = new Map<string, TableFormulaDefinition>();\n\tconst list: TableFormulaDefinition[] = [];\n\n\tfor (const definition of definitions) {\n\t\tconst normalizedId = definition.id.trim();\n\t\tif (!normalizedId) {\n\t\t\tthrow new Error(\"Formula id не может быть пустым\");\n\t\t}\n\n\t\tif (byId.has(normalizedId)) {\n\t\t\tthrow new Error(`Найден дублирующийся formulaId: ${normalizedId}`);\n\t\t}\n\n\t\tconst normalizedDefinition: TableFormulaDefinition = Object.freeze({\n\t\t\t...definition,\n\t\t\tid: normalizedId,\n\t\t\tname: definition.name.trim(),\n\t\t\tdescription: definition.description.trim(),\n\t\t\tkeywords: definition.keywords ? [...definition.keywords] : undefined\n\t\t});\n\n\t\tbyId.set(normalizedId, normalizedDefinition);\n\t\tlist.push(normalizedDefinition);\n\t}\n\n\treturn Object.freeze({\n\t\tlist: Object.freeze(list),\n\t\tbyId\n\t});\n}\n\nlet tableFormulaRegistry = createTableFormulaRegistry([]);\n\n/**\n * Устанавливает реестр формул host-приложения для всех formula runtime API.\n *\n * Конфигурация выполняется composition root до первого чтения, валидации или\n * компиляции формулы. Библиотека намеренно не содержит прикладной каталог.\n */\nexport function configureTableFormulaRegistry(registry: TableFormulaRegistry): void {\n\ttableFormulaRegistry = registry;\n}\n\nexport function getTableFormulaList(): readonly TableFormulaDefinition[] {\n\treturn tableFormulaRegistry.list;\n}\n\nexport function getTableFormulaById(formulaId: string | undefined): TableFormulaDefinition | undefined {\n\tconst normalizedId = formulaId?.trim();\n\tif (!normalizedId) return undefined;\n\treturn tableFormulaRegistry.byId.get(normalizedId);\n}\n","import { getTableFormulaById } from \"./registry\";\n\nimport type { TableFormulaContext, TableFormulaRowData } from \"./types\";\n\ntype TableFormulaContextInstrumentation = {\n\tonReadIndex?: (index: number) => void;\n\tonOutOfRangeIndex?: (index: number) => void;\n};\n\nfunction toFiniteNumberOrZero(value: unknown): number {\n\tconst normalized = Number(value);\n\treturn Number.isFinite(normalized) ? normalized : 0;\n}\n\nexport function createTableFormulaContext(args: {\n\trowData: TableFormulaRowData;\n\tkeys?: readonly string[];\n\tinstrumentation?: TableFormulaContextInstrumentation;\n}): TableFormulaContext {\n\t// TODO: duplicate createRowBasedFormatterContext src\\shared\\lib\\formatters\\rowBased\\context.ts\n\tconst keys = [...(args.keys ?? [])];\n\n\tconst readKey = (index: number): string | undefined => {\n\t\tif (!Number.isInteger(index) || index < 0) {\n\t\t\targs.instrumentation?.onOutOfRangeIndex?.(index);\n\t\t\treturn undefined;\n\t\t}\n\n\t\targs.instrumentation?.onReadIndex?.(index);\n\n\t\tif (index >= keys.length) {\n\t\t\targs.instrumentation?.onOutOfRangeIndex?.(index);\n\t\t\treturn undefined;\n\t\t}\n\n\t\treturn keys[index];\n\t};\n\n\tconst readValue = (index: number): unknown => {\n\t\tconst key = readKey(index);\n\t\tif (!key) return undefined;\n\t\treturn args.rowData[key];\n\t};\n\n\treturn {\n\t\tkey: readKey,\n\t\tvalue: readValue,\n\t\tnum: (index) => toFiniteNumberOrZero(readValue(index))\n\t};\n}\n\nexport type TableFormulaExecutionResult =\n\t| {\n\t\t\tok: true;\n\t\t\tvalue: number;\n\t  }\n\t| {\n\t\t\tok: false;\n\t\t\treason: \"formula_not_found\" | \"invalid_result\" | \"runtime_error\";\n\t  };\n\nexport type TableFormulaCompiledExecutor = (rowData: TableFormulaRowData) => TableFormulaExecutionResult;\n\ntype CompileTableFormulaResult =\n\t| {\n\t\t\tok: true;\n\t\t\texecute: TableFormulaCompiledExecutor;\n\t  }\n\t| {\n\t\t\tok: false;\n\t\t\treason: \"formula_not_found\";\n\t  };\n\nexport function compileTableFormula(args: { formulaId: string | undefined; keys?: readonly string[] }): CompileTableFormulaResult {\n\tconst formula = getTableFormulaById(args.formulaId);\n\tif (!formula) {\n\t\treturn { ok: false, reason: \"formula_not_found\" };\n\t}\n\n\tconst keys = [...(args.keys ?? [])];\n\tlet rowDataRef: TableFormulaRowData = {};\n\tconst context: TableFormulaContext = {\n\t\tkey: (index) => (Number.isInteger(index) && index >= 0 && index < keys.length ? keys[index] : undefined),\n\t\tvalue: (index) => {\n\t\t\tif (!Number.isInteger(index) || index < 0 || index >= keys.length) return undefined;\n\t\t\tconst key = keys[index];\n\t\t\tif (!key) return undefined;\n\t\t\treturn rowDataRef[key];\n\t\t},\n\t\tnum: (index) => {\n\t\t\tif (!Number.isInteger(index) || index < 0 || index >= keys.length) return 0;\n\t\t\tconst key = keys[index];\n\t\t\tif (!key) return 0;\n\t\t\treturn toFiniteNumberOrZero(rowDataRef[key]);\n\t\t}\n\t};\n\n\treturn {\n\t\tok: true,\n\t\texecute: (rowData) => {\n\t\t\trowDataRef = rowData;\n\n\t\t\ttry {\n\t\t\t\tconst value = formula.fn(context);\n\t\t\t\tif (!Number.isFinite(value)) {\n\t\t\t\t\treturn { ok: false, reason: \"invalid_result\" };\n\t\t\t\t}\n\n\t\t\t\treturn { ok: true, value };\n\t\t\t} catch {\n\t\t\t\treturn { ok: false, reason: \"runtime_error\" };\n\t\t\t}\n\t\t}\n\t};\n}\n\nexport function executeTableFormula(args: {\n\tformulaId: string | undefined;\n\trowData: TableFormulaRowData;\n\tkeys?: readonly string[];\n}): TableFormulaExecutionResult {\n\tconst compiled = compileTableFormula({\n\t\tformulaId: args.formulaId,\n\t\tkeys: args.keys\n\t});\n\tif (!compiled.ok) {\n\t\treturn { ok: false, reason: compiled.reason };\n\t}\n\n\treturn compiled.execute(args.rowData);\n}\n","/**\n * Подставляет ID упорядоченных зависимостей в шаблон превью формулы.\n *\n * Незаданные позиции остаются в виде $n, чтобы редактор мог показывать неполный\n * черновик. Подстановка однопроходная: ID сохраняются буквально, а полученный\n * текст предназначен только для отображения и никогда не исполняется.\n */\nexport function formatTableFormulaExpression(expressionTemplate: string, dependencies: readonly string[]): string {\n\treturn expressionTemplate.replace(/\\$([0-9]+)/g, (placeholder: string, index: string) => {\n\t\tconst dependencyId = dependencies[Number(index)];\n\t\treturn dependencyId === undefined || dependencyId === \"\" ? placeholder : dependencyId;\n\t});\n}\n","import { createTableFormulaContext } from \"./execute\";\nimport { getTableFormulaById } from \"./registry\";\n\ntype ValidationCode =\n\t| \"formula_not_found\"\n\t| \"dependency_index_out_of_range\"\n\t| \"dependency_not_available\"\n\t| \"unused_dependencies\"\n\t| \"formula_does_not_use_dependencies\"\n\t| \"formula_runtime_error\";\n\nexport interface TableFormulaValidationMessage {\n\tcode: ValidationCode;\n\tmessage: string;\n}\nexport interface TableFormulaDependenciesValidationResult {\n\tok: boolean;\n\terrors: TableFormulaValidationMessage[];\n\twarnings: TableFormulaValidationMessage[];\n\tusage: {\n\t\tusedDependencyIndexes: number[];\n\t\tusedDependencyIds: string[];\n\t\trequiredDependencyCount: number;\n\t};\n}\n\nfunction toSortedArray(items: Set<number>): number[] {\n\treturn [...items].sort((left, right) => left - right);\n}\n\nfunction createSampleRowData(dependencies: readonly string[], multiplier: number): Record<string, unknown> {\n\treturn dependencies.reduce<Record<string, unknown>>((acc, dependencyId, index) => {\n\t\tacc[dependencyId] = (index + 1) * multiplier;\n\t\treturn acc;\n\t}, {});\n}\n\nexport function validateTableFormulaDependencies(args: {\n\tformulaId: string | undefined;\n\tdependencies?: readonly string[];\n\tavailableColumnIds?: readonly string[];\n}): TableFormulaDependenciesValidationResult {\n\tconst errors: TableFormulaValidationMessage[] = [];\n\tconst warnings: TableFormulaValidationMessage[] = [];\n\n\tconst formula = getTableFormulaById(args.formulaId);\n\tconst dependencies = [...(args.dependencies ?? [])];\n\tconst availableColumnIds = args.availableColumnIds ?? [];\n\n\tif (!formula) {\n\t\terrors.push({\n\t\t\tcode: \"formula_not_found\",\n\t\t\tmessage: \"Формула не найдена в реестре.\"\n\t\t});\n\n\t\treturn {\n\t\t\tok: false,\n\t\t\terrors,\n\t\t\twarnings,\n\t\t\tusage: {\n\t\t\t\tusedDependencyIndexes: [],\n\t\t\t\tusedDependencyIds: [],\n\t\t\t\trequiredDependencyCount: 0\n\t\t\t}\n\t\t};\n\t}\n\n\tconst availableSet = new Set(availableColumnIds);\n\tconst missingDependencies = dependencies.filter((dependencyId) => !availableSet.has(dependencyId));\n\tif (missingDependencies.length > 0) {\n\t\terrors.push({\n\t\t\tcode: \"dependency_not_available\",\n\t\t\tmessage: `Не найдены среди доступных полей: ${missingDependencies.join(\", \")}.`\n\t\t});\n\t}\n\n\tconst usedIndexes = new Set<number>();\n\tconst outOfRangeIndexes = new Set<number>();\n\tlet runtimeErrorCount = 0;\n\n\tconst runValidationPass = (sampleRowData: Record<string, unknown>) => {\n\t\ttry {\n\t\t\tconst context = createTableFormulaContext({\n\t\t\t\trowData: sampleRowData,\n\t\t\t\tkeys: dependencies,\n\t\t\t\tinstrumentation: {\n\t\t\t\t\tonReadIndex: (index) => {\n\t\t\t\t\t\tusedIndexes.add(index);\n\t\t\t\t\t},\n\t\t\t\t\tonOutOfRangeIndex: (index) => {\n\t\t\t\t\t\toutOfRangeIndexes.add(index);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\t\tformula.fn(context);\n\t\t} catch {\n\t\t\truntimeErrorCount += 1;\n\t\t}\n\t};\n\n\t// Несколько прогонов повышают шанс увидеть обращения к индексам в разных ветках формулы.\n\trunValidationPass(createSampleRowData(dependencies, 100));\n\trunValidationPass(createSampleRowData(dependencies, -100));\n\n\tconst sortedUsedIndexes = toSortedArray(usedIndexes);\n\tconst requiredDependencyCount = sortedUsedIndexes.length > 0 ? sortedUsedIndexes[sortedUsedIndexes.length - 1] + 1 : 0;\n\n\tif (outOfRangeIndexes.size > 0) {\n\t\terrors.push({\n\t\t\tcode: \"dependency_index_out_of_range\",\n\t\t\tmessage: `Формула обращается к несуществующим индексам. Минимально требуется зависимостей: ${requiredDependencyCount}, выбрано: ${dependencies.length}.`\n\t\t});\n\t}\n\n\tif (sortedUsedIndexes.length === 0) {\n\t\twarnings.push({\n\t\t\tcode: \"formula_does_not_use_dependencies\",\n\t\t\tmessage: \"Формула не использует dependencies.\"\n\t\t});\n\t}\n\n\tconst unusedDependencies = dependencies.filter((_, index) => !usedIndexes.has(index));\n\tif (unusedDependencies.length > 0) {\n\t\twarnings.push({\n\t\t\tcode: \"unused_dependencies\",\n\t\t\tmessage: `Выбраны, но не используются формулой: ${unusedDependencies.join(\", \")}.`\n\t\t});\n\t}\n\n\tif (runtimeErrorCount > 0) {\n\t\twarnings.push({\n\t\t\tcode: \"formula_runtime_error\",\n\t\t\tmessage: \"На тестовых данных формула завершилась с ошибкой.\"\n\t\t});\n\t}\n\n\tconst usedDependencyIds = sortedUsedIndexes.map((index) => dependencies[index]).filter(Boolean);\n\n\treturn {\n\t\tok: errors.length === 0,\n\t\terrors,\n\t\twarnings,\n\t\tusage: {\n\t\t\tusedDependencyIndexes: sortedUsedIndexes,\n\t\t\tusedDependencyIds,\n\t\t\trequiredDependencyCount\n\t\t}\n\t};\n}\n"],"mappings":"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"}

package/dist/formulas/types.d.ts

@@ -9,6 +9,8 @@ export interface TableFormulaDefinition {
     id: string;
     name: string;
     description: string;
+    /** Шаблон превью с позициями $n; описывает выражение для человека и не участвует в выполнении fn. */
+    expressionTemplate?: string;
     args?: readonly string[];
     keywords?: readonly string[];
     fn: TableFormulaFn;

package/dist/formulas/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/formulas/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IACnC,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC3C,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,mBAAmB,KAAK,MAAM,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,EAAE,EAAE,cAAc,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/formulas/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IACnC,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC3C,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,mBAAmB,KAAK,MAAM,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,EAAE,EAAE,cAAc,CAAC;CACnB"}

package/dist/media/createNotificationTonePlayer.d.ts

@@ -0,0 +1,7 @@
+import { type NotificationToneNote, type NotificationTonePlayer } from "./notificationToneTypes";
+/**
+ * Один AudioContext и ограниченный набор осцилляторов. activate вызывается из
+ * жеста пользователя; доставка сама не пытается обойти autoplay policy.
+ */
+export declare function createNotificationTonePlayer(notes: readonly NotificationToneNote[]): NotificationTonePlayer;
+//# sourceMappingURL=createNotificationTonePlayer.d.ts.map

package/dist/media/createNotificationTonePlayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createNotificationTonePlayer.d.ts","sourceRoot":"","sources":["../../src/media/createNotificationTonePlayer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjG;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,GAAG,sBAAsB,CAmE3G"}

package/dist/media/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./breakpoints";
+export { createNotificationTonePlayer } from "./createNotificationTonePlayer";
+export { type NotificationToneNote, type NotificationTonePlayer } from "./notificationToneTypes";
 export * from "./getCurrentFontSize";
 export * from "./pxToEm";
 export * from "./responsive";

package/dist/media/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjG,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/media/index.js

@@ -1,148 +1,2 @@
-import { useCallback as e, useSyncExternalStore as t } from "react";
-//#region src/media/breakpoints.ts
-var n = {
-	mobileMax: 479.98 / 16,
-	tabletMin: 480 / 16,
-	tabletMax: 1151.98 / 16,
-	laptopMin: 1152 / 16
-}, r = 16, i = 1.2;
-function a(e) {
-	if (typeof window > "u" || typeof document > "u") return r;
-	let t = e ?? document.documentElement, n = window.getComputedStyle(t).fontSize, i = Number.parseFloat(n);
-	return !Number.isFinite(i) || i <= 0 ? r : i;
-}
-function o(e) {
-	if (typeof window > "u" || typeof document > "u") return i;
-	let t = e ?? document.documentElement, n = window.getComputedStyle(t).lineHeight, a = Number.parseFloat(n);
-	return !Number.isFinite(a) || a <= 0 ? i : a / r;
-}
-function s() {
-	return a() + o() * 10;
-}
-//#endregion
-//#region src/media/pxToEm.ts
-function c(e, t) {
-	return (e / (t ?? a())).toString();
-}
-//#endregion
-//#region src/media/responsive.ts
-function l(e) {
-	return typeof e != "object" || !e ? !1 : "mobile" in e || "tablet" in e || "laptop" in e || "desktop" in e;
-}
-function u(e, t) {
-	if (e !== void 0) return l(e) ? t === "mobile" ? e.mobile ?? e.tablet ?? e.laptop : t === "tablet" ? e.tablet ?? e.mobile ?? e.laptop : e.laptop ?? e.tablet ?? e.mobile : e;
-}
-function d(e, t, n) {
-	let r = { ...e };
-	for (let e of n) r[e] = u(r[e], t);
-	return r;
-}
-//#endregion
-//#region src/media/useMediaQuery.ts
-var f = () => {};
-function p(e, t) {
-	return typeof window > "u" || typeof window.matchMedia != "function" ? t : window.matchMedia(e).matches;
-}
-function m(e, t) {
-	if (typeof window > "u" || typeof window.matchMedia != "function") return f;
-	let n = window.matchMedia(e);
-	return typeof n.addEventListener == "function" ? (n.addEventListener("change", t), () => n.removeEventListener("change", t)) : (n.addListener(t), () => n.removeListener(t));
-}
-function h(n, { ssrFallback: r = !1 } = {}) {
-	let i = e((e) => m(n, e), [n]), a = e(() => p(n, r), [n, r]), o = e(() => r, [r]);
-	return t(i, a, o);
-}
-//#endregion
-//#region src/media/useMatchMedia.ts
-function g(e, t) {
-	return "addEventListener" in e ? (e.addEventListener("change", t), () => e.removeEventListener("change", t)) : (e.addListener(t), () => e.removeListener(t));
-}
-function _(e) {
-	let t = (t) => t * e, r = t(n.mobileMax), i = t(n.tabletMin), a = t(n.tabletMax), o = t(n.laptopMin);
-	return {
-		mobile: `(width <= ${r}px)`,
-		tablet: `(width >= ${i}px) and (width <= ${a}px)`,
-		laptop: `(width >= ${o}px)`
-	};
-}
-var v = {
-	matches: {
-		mobile: !1,
-		tablet: !1,
-		laptop: !1
-	},
-	activeBreakpoint: "laptop"
-}, y = .25, b = 80, x = v, S = null, C = [], w = 0, T = !1, E = null, D = null, O = null, k = null, A = /* @__PURE__ */ new Set();
-function j(e) {
-	return e.mobile ? "mobile" : e.tablet ? "tablet" : "laptop";
-}
-function M(e, t) {
-	return e.mobile === t.mobile && e.tablet === t.tablet && e.laptop === t.laptop;
-}
-function N(e) {
-	M(x.matches, e) || (x = {
-		matches: e,
-		activeBreakpoint: j(e)
-	}, A.forEach((e) => e()));
-}
-function P() {
-	S && N({
-		mobile: S.mobile.matches,
-		tablet: S.tablet.matches,
-		laptop: S.laptop.matches
-	});
-}
-function F() {
-	C.forEach((e) => e()), C = [];
-}
-function I(e = !1) {
-	if (typeof window > "u" || typeof document > "u") return;
-	let t = a();
-	if (!e && S && Math.abs(t - w) < y) return;
-	w = t, F();
-	let n = _(t);
-	S = {
-		mobile: window.matchMedia(n.mobile),
-		tablet: window.matchMedia(n.tablet),
-		laptop: window.matchMedia(n.laptop)
-	}, C = Object.keys(S).map((e) => g(S[e], P)), P();
-}
-function L() {
-	k && clearTimeout(k), k = setTimeout(() => {
-		k = null, I();
-	}, b);
-}
-function R() {
-	typeof window > "u" || typeof document > "u" || (E = new MutationObserver(L), E.observe(document.documentElement, {
-		attributes: !0,
-		attributeFilter: [
-			"style",
-			"class",
-			"data-font-size"
-		]
-	}), !(typeof ResizeObserver > "u") && (O = document.createElement("div"), O.style.position = "absolute", O.style.visibility = "hidden", O.style.pointerEvents = "none", O.style.width = "1em", O.style.height = "1px", O.style.overflow = "hidden", O.setAttribute("aria-hidden", "true"), (document.body ?? document.documentElement).appendChild(O), D = new ResizeObserver(L), D.observe(O)));
-}
-function z() {
-	F(), S = null, k &&= (clearTimeout(k), null), E &&= (E.disconnect(), null), D &&= (D.disconnect(), null), O?.parentNode && O.parentNode.removeChild(O), O = null, T = !1;
-}
-function B() {
-	T || typeof window > "u" || typeof document > "u" || (T = !0, I(!0), R());
-}
-function V(e) {
-	return typeof window > "u" || typeof document > "u" ? () => {} : (A.add(e), B(), () => {
-		A.delete(e), A.size === 0 && z();
-	});
-}
-function H() {
-	return x;
-}
-function U() {
-	return v;
-}
-function W() {
-	return t(V, H, U);
-}
-//#endregion
-export { n as BREAKPOINTS_EM, s as getControlHeight, a as getCurrentFontSize, o as getCurrentLineHeight, l as isResponsiveMap, c as pxToEm, d as resolveProps, u as resolveResponsiveValue, W as useMatchMedia, h as useMediaQuery };
-
-//# sourceMappingURL=index.js.map
+import { a as e, c as t, d as n, i as r, l as i, n as a, o, r as s, s as c, t as l, u } from "../chunks/media-WK38KtMl.js";
+export { n as BREAKPOINTS_EM, u as createNotificationTonePlayer, c as getControlHeight, t as getCurrentFontSize, i as getCurrentLineHeight, s as isResponsiveMap, o as pxToEm, r as resolveProps, e as resolveResponsiveValue, l as useMatchMedia, a as useMediaQuery };

package/dist/media/notificationToneTypes.d.ts

@@ -0,0 +1,13 @@
+/** Ноты синтезированного сигнала; временные значения заданы в секундах. */
+export type NotificationToneNote = Readonly<{
+    frequency: number;
+    offset: number;
+    duration: number;
+    volume: number;
+}>;
+export type NotificationTonePlayer = Readonly<{
+    activate: () => Promise<boolean>;
+    play: () => boolean;
+    dispose: () => void;
+}>;
+//# sourceMappingURL=notificationToneTypes.d.ts.map

package/dist/media/notificationToneTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notificationToneTypes.d.ts","sourceRoot":"","sources":["../../src/media/notificationToneTypes.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC7C,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;CACpB,CAAC,CAAC"}

package/dist/query-client/index.js

@@ -1,2 +1,2 @@
-import { C as e, D as t, E as n, S as r, T as i, _ as a, a as o, b as s, c, d as l, f as u, g as d, h as f, i as p, l as m, m as h, n as g, o as _, p as v, r as y, s as b, t as x, u as S, v as C, w, x as T, y as E } from "../chunks/query-client-Dj_zNE22.js";
+import { C as e, D as t, E as n, S as r, T as i, _ as a, a as o, b as s, c, d as l, f as u, g as d, h as f, i as p, l as m, m as h, n as g, o as _, p as v, r as y, s as b, t as x, u as S, v as C, w, x as T, y as E } from "../chunks/query-client-uQEbemFc.js";
 export { s as QUERY_RESTORED_DATA_PARSER, S as REACT_QUERY_PERSISTENCE_BUSTER, l as REACT_QUERY_PERSISTENCE_MAX_AGE, i as broadcastCacheEvent, u as clearSessionQueryPersistence, C as configureQueryPersistenceProjectAdapter, v as createIndexedDbQueryStorage, o as createQueryClient, h as createReactQueryPersister, T as createSessionQueryPersistenceMeta, E as getQueryPersistenceProjectAdapter, f as getSessionQueryPersistenceScope, w as installQueryInvalidationBroadcast, n as installReactQueryBroadcast, x as installSessionScopedQueryReset, p as installSessionScopedQueryResetLifecycle, g as isSessionScopedQuery, _ as onErrorOptimistic, b as onMutateOptimistic, c as onSettledOptimistic, m as onSuccessOptimistic, r as persistedQueryMeta, y as resetSessionScopedQueries, e as sessionScopedQueryMeta, t as setBroadcastFn, d as setSessionQueryPersistenceScope, a as shouldPersistQuery };

package/dist/session-storage/index.js

@@ -1,4 +1,4 @@
-import { uuidv4 as e } from "../crypto/index.js";
+import { t as e } from "../chunks/uuid-CUJPAbRY.js";
 //#region src/session-storage/sessionId.ts
 function t(t, n = e) {
 	if (typeof sessionStorage > "u") return n();

package/dist/three-scene/index.js

@@ -1,4 +1,4 @@
-import { useMediaQuery as e } from "../media/index.js";
+import { n as e } from "../chunks/media-WK38KtMl.js";
 import { useEffect as t, useState as n } from "react";
 //#region src/three-scene/threeSceneAvailability.ts
 var r = {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ryuzaki13/react-foundation-lib",
-	"version": "2.26.0",
+	"version": "2.28.0",
 	"description": "Reusable React and TypeScript foundation utilities, hooks, and primitives.",
 	"license": "MIT",
 	"author": "Ryuzaki13",
@@ -49,6 +49,10 @@
 			"types": "./dist/binary/index.d.ts",
 			"import": "./dist/binary/index.js"
 		},
+		"./browser-notifications": {
+			"types": "./dist/browser-notifications/index.d.ts",
+			"import": "./dist/browser-notifications/index.js"
+		},
 		"./bounded-copy-stack": {
 			"types": "./dist/bounded-copy-stack/index.d.ts",
 			"import": "./dist/bounded-copy-stack/index.js"

package/src/browser-notifications/README.md

@@ -0,0 +1,21 @@
+# Браузерные уведомления
+
+`createBrowserNotificationPresenter` из `/browser-notifications` предоставляет
+явный запрос разрешения и отменяемую публикацию системного уведомления.
+Создание не обращается к браузеру; SSR не вызывает API. Метод `show` предпочитает
+уже активный Service Worker, а без него использует desktop Notification API.
+Приложение обрабатывает `notificationclick` своего worker, проверяя URL из data.
+Серверная Web Push доставка и регистрация worker не входят в контракт.
+
+`requestPermission` вызывается непосредственно из пользовательского жеста.
+Отказ не запрашивается повторно. HTTPS/localhost и поддержка API обязательны;
+системные ограничения остаются у браузера. `show` возвращает немедленный disposer,
+который закрывает также позднюю SW-публикацию; `dispose` завершает все свои.
+События клика desktop передаются в `onOpen`, ошибки доставки — в `onError`.
+
+Связанные независимые primitives: `/media` экспортирует
+`createNotificationTonePlayer` с плавным синусоидальным сигналом до 1,5 секунды
+и явной `activate` из жеста пользователя; `/dom` предоставляет
+`installFaviconOverride` с симметричным восстановлением favicon links.
+Продуктовые правила, интервалы оповещения, тексты, настройки и дедупликация
+остаются у вызывающего приложения.

package/src/formulas/README.mdx

@@ -45,6 +45,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 - описывает типизированный контракт числовой формулы;
 - связывает dependency indexes с полями текущей строки;
+- формирует текстовое превью выражения с ID выбранных зависимостей;
 - создаёт нормализованный реестр формул host-приложения;
 - хранит один активный реестр в текущем экземпляре модуля;
 - выполняет формулы без выбрасывания их runtime-ошибок наружу;
@@ -81,6 +82,7 @@ import {
 	executeTableFormula,
 	getTableFormulaById,
 	getTableFormulaList,
+	formatTableFormulaExpression,
 	validateTableFormulaDependencies
 } from "@ryuzaki13/react-foundation-lib/formulas";
 
@@ -222,6 +224,7 @@ interface TableFormulaDefinition {
 	id: string;
 	name: string;
 	description: string;
+	expressionTemplate?: string;
 	args?: readonly string[];
 	keywords?: readonly string[];
 	fn: TableFormulaFn;
@@ -266,6 +269,33 @@ description: "100 * $0 / ($0 + $1)";
 
 Factory trim-ит строку, но не анализирует выражение. `$0`, `$1` — только принятая человеком нотация документации, а не parser syntax.
 
+### `expressionTemplate`
+
+Необязательный шаблон компактного превью. В отличие от `description`, он содержит только отображаемое выражение:
+
+```ts
+expressionTemplate: "$0 / $1";
+```
+
+Индекс `$n` соответствует позиции в упорядоченном списке зависимостей. Шаблон сохраняется буквально; registry, execution и validation не требуют его наличия. Ранее объявленные definitions без этого поля сохраняют прежний контракт.
+
+Шаблон служит описанием основной операции для человека. Он не заменяет `fn`, не исполняется и не обязан воспроизводить все защитные ветвления функции, например возврат нуля при нулевом делителе. За соответствие шаблона операции отвечает автор definition.
+
+### `formatTableFormulaExpression(expressionTemplate, dependencies)`
+
+Чистая функция подставляет ID зависимостей в позиции `$n` за один проход:
+
+```ts
+import { formatTableFormulaExpression } from "@ryuzaki13/react-foundation-lib/formulas";
+
+formatTableFormulaExpression("$0 / $1", ["FIELD_X", "FIELD_Y"]); // "FIELD_X / FIELD_Y"
+formatTableFormulaExpression("$0 / $1", ["FIELD_X"]); // "FIELD_X / $1"
+```
+
+Повторные вхождения заменяются, `$1` и `$10` различаются. Незаданный или пустой ID оставляет исходный маркер; пробелы и специальные символы в ID сохраняются. Подставленные ID не обрабатываются повторно, входной массив не изменяется. Операторы, скобки и остальной текст шаблона не анализируются.
+
+Пустая строка возвращается без изменений. Host UI самостоятельно выбирает сообщение для отсутствующего или пустого шаблона и отображает результат как текст.
+
 ### `args`
 
 Необязательные подписи positional arguments:
@@ -1035,7 +1065,7 @@ app composition / registries
 - TypeScript проверяет написанные definitions;
 - обычные unit-tests видят функцию напрямую.
 
-`description` может содержать формулу для человека, но runtime выполняет только `fn`, заранее включённую разработчиком в registry.
+`description` и `expressionTemplate` могут содержать формулу для человека, но runtime выполняет только `fn`, заранее включённую разработчиком в registry.
 
 ### Доверенный код всё равно требует дисциплины
 
@@ -1204,6 +1234,7 @@ Promise не является конечным number и даст `invalid_resul
 | `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              |