Довідка

Довідник формул і коду

Посібник для новачків, блоки, код формул і повний скрипт. Картки довідника генеруються з registry.

Mom · Help

Ласкаво просимо. Тут описано логіку калькулятора в блоках, коді формули та повному скрипті — усе редагує одне дерево формули.

Що таке цей калькулятор?

Калькулятор — це конфігурація (CalculatorConfig): поля вводу, константи, опційні макроси, проміжні розрахунки (calc) і фінальні результати (output). У кожного calc/output одна формула у вигляді дерева (AST). Білдер дозволяє редагувати дерево блоками або текстом — обидва види читають і пишуть одне й те саме дерево, тож дві незалежні формули не потрібні.

На екрані калькулятора користувач вводить кількості та властивості; застосунок обходить граф залежностей і обчислює формули в правильному порядку.

Частини конфігурації

Частина	Бачить користувач?	Роль
Input (`field_*`)	Так — qty + властивості	Те, що вводить користувач
Constant (`const_*`)	Ні	Фіксовані числа в формулах
Macro (`macro_*`)	Ні	Повторюваний фрагмент; перетягується як змінна
Calculation (`calc_*`)	Ні (проміжний)	Прихований крок для інших формул
Output (`output_*`)	Так — після Розрахувати	Підсумок для користувача

Авто-розрахунки (бейдж «Auto») з’являються при «кількість × властивість» на полі. Вони в read-only вкладці скрипта і в палитрі як посилання на calc.

Одна формула — три види

CalculatorConfig.expression (JSON AST)  ← єдине джерело правди в БД
        ↑ parse (registry)     ↓ format (registry)
   текст коду формули         UI блоків

Блоки — workspace у стилі Scratch.
Код — та сама мова в formula { … } або в повному скрипті.
Preview («Читається як» / breakdown) — текст з AST.

Новий оператор додається один раз у lib/formula/nodes/primitives/*.node.ts і з’являється в блоках, коді, autocomplete та цій довідці.

Редактор блоків — покроково

Відкрийте розрахунок або результат і розгорніть Логіку розрахунку.
Оберіть вид Блоки або Код + блоки.
Натисніть ＋ у слоті або перетягніть з палитри.
Палитра → Блоки: поля, константи, макроси, інші calc/output.
Палитра → Дії: + − × ÷, порівняння, ( ), SUM, IF, ROUND, агрегати по рядках.
⠿ — перетягнути блок; вкладення в SUM / IF / дужки.
Читається як — текст формули, синхронний з блоками.

IF і ROUND — кольорові дужки з підписаними слотами. SUM — аргументи через кому всередині дужки.

Код формули — покроково

У тій же панелі — Код або Код + блоки.
Приклад:

formula {
  local subtotal = field_item.qty * field_item.var_cost
  return ROUND(subtotal * const_markup, 2)
}

local лише перед return. Імена — lowercase.
Посилання: field_id.qty, field_id.var_cost, const_id, calc_id, output_id, macro_id.
Порівняння → 1 або 0. IF(умова, так, ні) — умова істинна, якщо ≠ 0.
Невалідний код не потрапляє в блоки, поки парсер не прийме текст.
Ctrl/Cmd+S у sheet — застосувати весь проєкт.

Autocomplete (Ctrl+Space) — поля, функції, ключові слова скрипта.

Синхронізація блоків і коду

Блоки → код оновлюється одразу (format з registry).
Код → блоки після паузи, коли текст парситься.
Код у тулбарі — повний скрипт по вкладках. Застосувати → той самий CalculatorConfig, що й UI блоків.
Зміни в білдері без правок у sheet — авто-перезавантаження скрипта.
Якщо sheet редагували — банер Перезавантажити з білдера.

У БД лишається один JSON — sheet лише текстове відображення.

Повний скрипт (вкладка Код)

Кнопка Код у білдері відкриває всі декларації:

Вкладка	Зміст
`inputs.calc`	`input field_… { … }`
`constants.calc`	`constant const_… { … }`
`macros.calc`	`macro macro_… { … }`
`calculations.calc`	`calc calc_… { … }`
`outputs.calc`	`output output_… { … }`
`auto-calculations.calc`	read-only авто-підсумки

Директиви: #include, #use (шаблон). Деталі — вкладка Скрипт калькулятора нижче.

У репозиторії: docs/calculator-script.md.

Як обчислюються значення

Збираються qty і рядки таблиць.
Авто-calc і calc — у порядку залежностей (цикли виявляються).
Кожна формула — через registry.
Потім outputs.
local лише всередині одного output.

Ділення на 0 → 0 і попередження в логах. ROUND(x, n) — n від 0 до 10.

Поради новачкам

Почніть з пресету (типографія, салон, друкарня).
Довгі кроки — у calc, короткі — у output.
Макроси — для повторюваних виразів.
Таблиці рядків: SUM_ROWS(…) у коді або SUM rows у блоках.
? на блоках палитри та Довідка в шапці — ця сторінка.
Тести: npx vitest run tests/formula.