From b7cd0cf5bfba632f94a93f7355d8315f882e26f2 Mon Sep 17 00:00:00 2001
From: akira69 <akira69@gmail.com>
Date: Tue, 10 Mar 2026 00:40:32 -0500
Subject: [PATCH 1/3] feat(settings): formula extra fields with JSON logic
 authoring and API integration

---
 JSON_LOGIC_SPIKE.md                           |  177 ++
 client/package-lock.json                      |  232 +++
 client/package.json                           |   10 +-
 client/public/locales/en/common.json          |  165 +-
 client/src/index.tsx                          |   22 +
 client/src/pages/filaments/list.tsx           |   81 +-
 client/src/pages/filaments/show.tsx           |   20 +-
 client/src/pages/help/index.tsx               |  473 ++++-
 .../printing/spoolQrCodePrintingDialog.tsx    |   43 +-
 .../pages/settings/complexFieldsSettings.tsx  | 1834 +++++++++++++++++
 .../pages/settings/extraFieldsSettings.tsx    |  109 +-
 client/src/pages/settings/index.tsx           |    1 -
 client/src/pages/spools/list.tsx              |   79 +-
 client/src/pages/spools/show.tsx              |   20 +-
 client/src/pages/vendors/list.tsx             |   81 +-
 client/src/pages/vendors/show.tsx             |   20 +-
 client/src/utils/formulaFields.ts             |  536 +++++
 client/src/utils/queryFields.ts               |  121 ++
 scripts/json_logic_parity.py                  |  304 +++
 scripts/pr-preflight.sh                       |  174 ++
 spoolman/api/v1/field.py                      |  105 +
 spoolman/api/v1/filament.py                   |   70 +-
 spoolman/api/v1/models.py                     |   23 +-
 spoolman/api/v1/spool.py                      |   65 +-
 spoolman/api/v1/vendor.py                     |   65 +-
 spoolman/derived_fields.py                    |  613 ++++++
 spoolman/settings.py                          |    4 +
 .../fields/json_logic_parity_fixtures.json    |  142 ++
 .../tests/fields/test_derived.py              |   60 +
 .../tests/fields/test_derived_api.py          |   98 +
 30 files changed, 5677 insertions(+), 70 deletions(-)
 create mode 100644 JSON_LOGIC_SPIKE.md
 create mode 100644 client/src/pages/settings/complexFieldsSettings.tsx
 create mode 100644 client/src/utils/formulaFields.ts
 create mode 100644 scripts/json_logic_parity.py
 create mode 100755 scripts/pr-preflight.sh
 create mode 100644 spoolman/derived_fields.py
 create mode 100644 tests_integration/tests/fields/json_logic_parity_fixtures.json
 create mode 100644 tests_integration/tests/fields/test_derived.py
 create mode 100644 tests_integration/tests/fields/test_derived_api.py

diff --git a/JSON_LOGIC_SPIKE.md b/JSON_LOGIC_SPIKE.md
new file mode 100644
index 000000000..44af8cae2
--- /dev/null
+++ b/JSON_LOGIC_SPIKE.md
@@ -0,0 +1,177 @@
+# JSON Logic Spike (Clean-Cut) for Formula Extra Fields
+
+## Status
+- Owner: TBD
+- Branch: `feat/complex-fields-framework` (PR #874 context)
+- Date: 2026-03-05
+- Decision type: Spike RFC (implementation-first, no legacy compatibility)
+
+## Background
+Current formula fields use a custom expression syntax/evaluator with limited typing and helper coverage.
+We want richer boolean/date/text logic and safer execution semantics without continuing ad-hoc parser growth.
+
+Relevant requests:
+- [#795](https://github.com/Donkie/Spoolman/issues/795) Labels: Date formatting
+- [#853](https://github.com/Donkie/Spoolman/issues/853) Sort by hue
+- [#870](https://github.com/Donkie/Spoolman/issues/870) Show empty spool weight column
+- [#783](https://github.com/Donkie/Spoolman/issues/783) Extra action buttons per spool (partially related)
+
+## Goals
+- Replace the formula expression engine with JSON Logic for formula extra fields.
+- Support result types: `number`, `text`, `boolean`, `date`, `datetime`, `time`.
+- Enable richer operators: logical, comparison, conditional, string, and date helpers.
+- Enforce frontend/backend evaluation parity for previews and rendered values.
+- Keep execution safe and deterministic (no unrestricted eval).
+
+## Non-Goals
+- Backward compatibility with old formula syntax.
+- Automatic migration of existing formula definitions.
+- Replacing complex extra fields that add custom UI/actions/workflows.
+- Server-side indexed filtering/sorting on computed values in this spike.
+
+## Decision (Proposed)
+- Use JSON Logic as the canonical formula representation.
+- Store formulas as JSON AST only.
+- Remove legacy expression parser/evaluator once spike implementation is accepted.
+
+## Runtime Candidate Snapshot (2026-03-05)
+| Candidate | Role | License | Activity signal | Notes |
+| --- | --- | --- | --- | --- |
+| `json-logic/json-logic-engine` | Frontend runtime | MIT | pushed 2026-01-21 | Active JS implementation with custom operator support. |
+| `jwadhams/json-logic-js` | Frontend/runtime reference | MIT | pushed 2024-07-09 | Canonical older implementation, broader adoption but slower recent change pace. |
+| `nadirizr/json-logic-py` | Backend runtime | MIT | pushed 2023-12-19 | Usable baseline, but older activity and parity risk with modern JS engines. |
+| `llnl/jsonlogic` | Python tooling (non-evaluator) | MIT | pushed 2026-03-05 | Provides JSON Logic expression generation helpers, not a direct evaluator runtime. |
+| `cloud-custodian/cel-python` | Alternative (non-JSON Logic) | Apache-2.0 | pushed 2026-02-17 | Strong typed alternative if JSON Logic parity fails. |
+
+Proposed spike baseline:
+- Frontend: `json-logic-engine`
+- Backend: start with `nadirizr/json-logic-py` for evaluator parity harness; reassess additional evaluator candidates after fixture runs.
+
+## Proposed Architecture
+### Data model
+- `DerivedFieldDefinition` stores:
+- `result_type`
+- `expression_json` (JSON object, required)
+- Keep current surfaces/column toggle behavior unchanged.
+
+### Backend
+- Add a JSON Logic evaluator wrapper in Python.
+- Provide a strict operator allowlist.
+- Add custom operators for Spoolman domain helpers:
+- `today`, `date_only`, `time_only`, `days_between`, `hours_between`, `hue_from_hex`, `coalesce`
+- Validate AST at save-time with:
+- operator allowlist checks
+- reference format checks
+- result type compatibility checks
+- Preview endpoint accepts JSON AST and sample values.
+
+### Frontend
+- Formula editor becomes JSON Logic editor:
+- raw JSON textarea in spike phase
+- clickable chips for references/operators
+- preview panel unchanged in behavior
+- Type-aware helper palette by selected `result_type`.
+- Keep current list/show/template surface controls.
+
+## Operator/Helper Catalog (Initial)
+### Logical and conditional
+- `and`, `or`, `!`, `if`, `??` (or `coalesce`)
+
+### Comparison
+- `==`, `!=`, `<`, `<=`, `>`, `>=`
+
+### Numeric
+- `+`, `-`, `*`, `/`, `%`, `abs`, `min`, `max`, `round`, `floor`, `ceil`
+
+### Text
+- `cat`, `substr`, `lower`, `upper`, `trim`, `length`, `replace`
+
+### Date and time
+- `today`, `year`, `month`, `day`, `hour`, `minute`, `second`, `timestamp`
+- `date_only`, `time_only`, `days_between`, `hours_between`
+
+## Result Type Rules (Draft)
+- `number`: numeric expressions only.
+- `text`: string output or explicit stringify.
+- `boolean`: logical/comparison output.
+- `date`: ISO `YYYY-MM-DD`.
+- `datetime`: ISO datetime string in UTC.
+- `time`: ISO `HH:MM:SS`.
+
+Validation should fail early when inferred output does not match `result_type`.
+
+## Scope Boundaries vs Complex Extra Fields
+JSON Logic formula fields can cover:
+- computed columns
+- status flags
+- derived display values
+
+Complex extra fields remain for:
+- UI actions/buttons/workflows
+- module-defined interactions beyond scalar value computation
+
+## Implementation Plan
+1. Backend foundation
+- Add evaluator wrapper and allowlisted custom ops.
+- Add AST validation and type checks.
+- Update preview endpoint to JSON AST payload.
+
+2. Frontend foundation
+- Replace expression editor with JSON AST editor UI.
+- Add reference/operator chip insertion.
+- Keep preview UX and surface controls.
+
+3. Integration
+- Replace runtime formula evaluation in list/show/template render paths.
+- Remove old formula parser/evaluator modules.
+
+4. Tests
+- Backend unit tests for ops, validation, and type enforcement.
+- Frontend tests for insertion and preview payload shape.
+- Parity tests using shared fixtures for FE and BE outputs.
+
+## Risks
+- JSON authoring UX can be heavy without a visual builder.
+- FE/BE library semantic differences must be normalized.
+- Date/time coercion edge cases can be surprising if not tightly specified.
+
+## Immediate Next Step Checklist (Phase 0, 1-2 days)
+- Build a 20-case parity fixture set (`tests_integration` + frontend fixture file):
+- arithmetic, boolean logic, null/coalesce, string ops, date helpers, hue helper, invalid syntax, invalid type.
+- Run fixture set against two backend candidates and one frontend candidate.
+- Record mismatches with exact operator semantics and type coercion behavior.
+- Select backend runtime and lock the operator subset for v1.
+- Freeze UTC/date behavior in writing (`today` allowed, `now` deferred).
+- Finalize API contract for preview/save payload (`expression_json` only).
+
+## Phase 0 Snapshot (2026-03-05)
+- Fixture set created: `tests_integration/tests/fields/json_logic_parity_fixtures.json` (20 cases).
+- Runner created: `scripts/json_logic_parity.py`.
+- Backend execution baseline:
+- Engine: `json-logic-py` (sourced directly from GitHub due blocked PyPI access in this environment)
+- Result: **20/20 pass**
+- Meaning: operator set and custom helper wiring in the harness are viable for spike phase.
+
+## Phase 1 Snapshot (2026-03-05)
+- Backend API accepts `expression_json` for preview/save with allowlisted JSON Logic operators and custom helpers.
+- Frontend formula runtime evaluates `expression_json` when present, with legacy string expressions as fallback.
+- Settings dependency checks now resolve custom-field references from both legacy expressions and JSON Logic `var` nodes.
+- Formula editor accepts an optional `Expression JSON (JSON Logic)` payload for preview/save during transition.
+
+## Spike Exit Criteria
+- At least 15 golden fixture expressions pass identically in FE and BE.
+- Save-time validation blocks invalid operators/references/types.
+- Preview and runtime rendering are consistent for all result types.
+- Old expression engine fully removable without hidden dependencies.
+
+## Open Questions
+- Which Python JSON Logic library will be used, and does it support needed custom ops cleanly?
+- Should `now()` be excluded initially to avoid time-volatile values in displayed columns?
+- Do we allow nested object outputs at all, or scalar-only forever?
+- Should date/time helpers always be UTC-only in v1?
+
+## Deliverables
+- `JSON_LOGIC_SPIKE.md` (this RFC)
+- Prototype backend evaluator + validation
+- Prototype frontend JSON editor + preview
+- Test report with parity matrix and go/no-go recommendation
diff --git a/client/package-lock.json b/client/package-lock.json
index b19647a12..976446c60 100644
--- a/client/package-lock.json
+++ b/client/package-lock.json
@@ -9,6 +9,7 @@
       "version": "0.23.1",
       "dependencies": {
         "@ant-design/v5-patch-for-react-19": "^1.0.3",
+        "@codemirror/lang-json": "^6.0.2",
         "@loadable/component": "^5.16.7",
         "@refinedev/antd": "^6.0.3",
         "@refinedev/core": "^5.0.7",
@@ -17,6 +18,7 @@
         "@refinedev/simple-rest": "^6.0.1",
         "@tanstack/react-query": "^5.90.16",
         "@tanstack/react-query-devtools": "^5.91.2",
+        "@uiw/react-codemirror": "^4.25.7",
         "@yudiel/react-qr-scanner": "^2.5.0",
         "axios": "^1.13.2",
         "dayjs": "^1.11.10",
@@ -2020,6 +2022,109 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@codemirror/autocomplete": {
+      "version": "6.20.1",
+      "resolved": "https://registry.npmjs.org/@codemirror/autocomplete/-/autocomplete-6.20.1.tgz",
+      "integrity": "sha512-1cvg3Vz1dSSToCNlJfRA2WSI4ht3K+WplO0UMOgmUYPivCyy2oueZY6Lx7M9wThm7SDUBViRmuT+OG/i8+ON9A==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/language": "^6.0.0",
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.17.0",
+        "@lezer/common": "^1.0.0"
+      }
+    },
+    "node_modules/@codemirror/commands": {
+      "version": "6.10.2",
+      "resolved": "https://registry.npmjs.org/@codemirror/commands/-/commands-6.10.2.tgz",
+      "integrity": "sha512-vvX1fsih9HledO1c9zdotZYUZnE4xV0m6i3m25s5DIfXofuprk6cRcLUZvSk3CASUbwjQX21tOGbkY2BH8TpnQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/language": "^6.0.0",
+        "@codemirror/state": "^6.4.0",
+        "@codemirror/view": "^6.27.0",
+        "@lezer/common": "^1.1.0"
+      }
+    },
+    "node_modules/@codemirror/lang-json": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/@codemirror/lang-json/-/lang-json-6.0.2.tgz",
+      "integrity": "sha512-x2OtO+AvwEHrEwR0FyyPtfDUiloG3rnVTSZV1W8UteaLL8/MajQd8DpvUb2YVzC+/T18aSDv0H9mu+xw0EStoQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/language": "^6.0.0",
+        "@lezer/json": "^1.0.0"
+      }
+    },
+    "node_modules/@codemirror/language": {
+      "version": "6.12.2",
+      "resolved": "https://registry.npmjs.org/@codemirror/language/-/language-6.12.2.tgz",
+      "integrity": "sha512-jEPmz2nGGDxhRTg3lTpzmIyGKxz3Gp3SJES4b0nAuE5SWQoKdT5GoQ69cwMmFd+wvFUhYirtDTr0/DRHpQAyWg==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.23.0",
+        "@lezer/common": "^1.5.0",
+        "@lezer/highlight": "^1.0.0",
+        "@lezer/lr": "^1.0.0",
+        "style-mod": "^4.0.0"
+      }
+    },
+    "node_modules/@codemirror/lint": {
+      "version": "6.9.5",
+      "resolved": "https://registry.npmjs.org/@codemirror/lint/-/lint-6.9.5.tgz",
+      "integrity": "sha512-GElsbU9G7QT9xXhpUg1zWGmftA/7jamh+7+ydKRuT0ORpWS3wOSP0yT1FOlIZa7mIJjpVPipErsyvVqB9cfTFA==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.35.0",
+        "crelt": "^1.0.5"
+      }
+    },
+    "node_modules/@codemirror/search": {
+      "version": "6.6.0",
+      "resolved": "https://registry.npmjs.org/@codemirror/search/-/search-6.6.0.tgz",
+      "integrity": "sha512-koFuNXcDvyyotWcgOnZGmY7LZqEOXZaaxD/j6n18TCLx2/9HieZJ5H6hs1g8FiRxBD0DNfs0nXn17g872RmYdw==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.37.0",
+        "crelt": "^1.0.5"
+      }
+    },
+    "node_modules/@codemirror/state": {
+      "version": "6.5.4",
+      "resolved": "https://registry.npmjs.org/@codemirror/state/-/state-6.5.4.tgz",
+      "integrity": "sha512-8y7xqG/hpB53l25CIoit9/ngxdfoG+fx+V3SHBrinnhOtLvKHRyAJJuHzkWrR4YXXLX8eXBsejgAAxHUOdW1yw==",
+      "license": "MIT",
+      "dependencies": {
+        "@marijn/find-cluster-break": "^1.0.0"
+      }
+    },
+    "node_modules/@codemirror/theme-one-dark": {
+      "version": "6.1.3",
+      "resolved": "https://registry.npmjs.org/@codemirror/theme-one-dark/-/theme-one-dark-6.1.3.tgz",
+      "integrity": "sha512-NzBdIvEJmx6fjeremiGp3t/okrLPYT0d9orIc7AFun8oZcRk58aejkqhv6spnz4MLAevrKNPMQYXEWMg4s+sKA==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/language": "^6.0.0",
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.0.0",
+        "@lezer/highlight": "^1.0.0"
+      }
+    },
+    "node_modules/@codemirror/view": {
+      "version": "6.39.16",
+      "resolved": "https://registry.npmjs.org/@codemirror/view/-/view-6.39.16.tgz",
+      "integrity": "sha512-m6S22fFpKtOWhq8HuhzsI1WzUP/hB9THbDj0Tl5KX4gbO6Y91hwBl7Yky33NdvB6IffuRFiBxf1R8kJMyXmA4Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/state": "^6.5.0",
+        "crelt": "^1.0.6",
+        "style-mod": "^4.1.0",
+        "w3c-keyname": "^2.2.4"
+      }
+    },
     "node_modules/@colors/colors": {
       "version": "1.5.0",
       "resolved": "https://registry.npmjs.org/@colors/colors/-/colors-1.5.0.tgz",
@@ -2948,6 +3053,41 @@
         "@jridgewell/sourcemap-codec": "^1.4.14"
       }
     },
+    "node_modules/@lezer/common": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.1.tgz",
+      "integrity": "sha512-6YRVG9vBkaY7p1IVxL4s44n5nUnaNnGM2/AckNgYOnxTG2kWh1vR8BMxPseWPjRNpb5VtXnMpeYAEAADoRV1Iw==",
+      "license": "MIT"
+    },
+    "node_modules/@lezer/highlight": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@lezer/highlight/-/highlight-1.2.3.tgz",
+      "integrity": "sha512-qXdH7UqTvGfdVBINrgKhDsVTJTxactNNxLk7+UMwZhU13lMHaOBlJe9Vqp907ya56Y3+ed2tlqzys7jDkTmW0g==",
+      "license": "MIT",
+      "dependencies": {
+        "@lezer/common": "^1.3.0"
+      }
+    },
+    "node_modules/@lezer/json": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@lezer/json/-/json-1.0.3.tgz",
+      "integrity": "sha512-BP9KzdF9Y35PDpv04r0VeSTKDeox5vVr3efE7eBbx3r4s3oNLfunchejZhjArmeieBH+nVOpgIiBJpEAv8ilqQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@lezer/common": "^1.2.0",
+        "@lezer/highlight": "^1.0.0",
+        "@lezer/lr": "^1.0.0"
+      }
+    },
+    "node_modules/@lezer/lr": {
+      "version": "1.4.8",
+      "resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.4.8.tgz",
+      "integrity": "sha512-bPWa0Pgx69ylNlMlPvBPryqeLYQjyJjqPx+Aupm5zydLIF3NE+6MMLT8Yi23Bd9cif9VS00aUebn+6fDIGBcDA==",
+      "license": "MIT",
+      "dependencies": {
+        "@lezer/common": "^1.0.0"
+      }
+    },
     "node_modules/@loadable/component": {
       "version": "5.16.7",
       "resolved": "https://registry.npmjs.org/@loadable/component/-/component-5.16.7.tgz",
@@ -2969,6 +3109,12 @@
         "react": "^16.3.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
       }
     },
+    "node_modules/@marijn/find-cluster-break": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@marijn/find-cluster-break/-/find-cluster-break-1.0.2.tgz",
+      "integrity": "sha512-l0h88YhZFyKdXIFNfSWpyjStDjGHwZ/U7iobcK1cQQD8sejsONdQtTVU+1wVN1PBw40PiiHB1vA5S7VTfQiP9g==",
+      "license": "MIT"
+    },
     "node_modules/@nodelib/fs.scandir": {
       "version": "2.1.5",
       "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",
@@ -4912,6 +5058,59 @@
         "url": "https://opencollective.com/typescript-eslint"
       }
     },
+    "node_modules/@uiw/codemirror-extensions-basic-setup": {
+      "version": "4.25.7",
+      "resolved": "https://registry.npmjs.org/@uiw/codemirror-extensions-basic-setup/-/codemirror-extensions-basic-setup-4.25.7.tgz",
+      "integrity": "sha512-tPV/AGjF4yM22D5mnyH7EuYBkWO05wF5Y4x3lmQJo6LuHmhjh0RQsVDjqeIgNOkXT3UO9OdkL4dzxw465/JZVg==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/autocomplete": "^6.0.0",
+        "@codemirror/commands": "^6.0.0",
+        "@codemirror/language": "^6.0.0",
+        "@codemirror/lint": "^6.0.0",
+        "@codemirror/search": "^6.0.0",
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.0.0"
+      },
+      "funding": {
+        "url": "https://jaywcjlove.github.io/#/sponsor"
+      },
+      "peerDependencies": {
+        "@codemirror/autocomplete": ">=6.0.0",
+        "@codemirror/commands": ">=6.0.0",
+        "@codemirror/language": ">=6.0.0",
+        "@codemirror/lint": ">=6.0.0",
+        "@codemirror/search": ">=6.0.0",
+        "@codemirror/state": ">=6.0.0",
+        "@codemirror/view": ">=6.0.0"
+      }
+    },
+    "node_modules/@uiw/react-codemirror": {
+      "version": "4.25.7",
+      "resolved": "https://registry.npmjs.org/@uiw/react-codemirror/-/react-codemirror-4.25.7.tgz",
+      "integrity": "sha512-s/EbEe0dFANWEgfLbfdIrrOGv0R7M1XhkKG3ShroBeH6uP9pVNQy81YHOLRCSVcytTp9zAWRNfXR/+XxZTvV7w==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.18.6",
+        "@codemirror/commands": "^6.1.0",
+        "@codemirror/state": "^6.1.1",
+        "@codemirror/theme-one-dark": "^6.0.0",
+        "@uiw/codemirror-extensions-basic-setup": "4.25.7",
+        "codemirror": "^6.0.0"
+      },
+      "funding": {
+        "url": "https://jaywcjlove.github.io/#/sponsor"
+      },
+      "peerDependencies": {
+        "@babel/runtime": ">=7.11.0",
+        "@codemirror/state": ">=6.0.0",
+        "@codemirror/theme-one-dark": ">=6.0.0",
+        "@codemirror/view": ">=6.0.0",
+        "codemirror": ">=6.0.0",
+        "react": ">=17.0.0",
+        "react-dom": ">=17.0.0"
+      }
+    },
     "node_modules/@umijs/route-utils": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/@umijs/route-utils/-/route-utils-4.0.3.tgz",
@@ -6024,6 +6223,21 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/codemirror": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/codemirror/-/codemirror-6.0.2.tgz",
+      "integrity": "sha512-VhydHotNW5w1UGK0Qj96BwSk/Zqbp9WbnyK2W/eVMv4QyF41INRGpjUhFJY7/uDNuudSc33a/PKr4iDqRduvHw==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/autocomplete": "^6.0.0",
+        "@codemirror/commands": "^6.0.0",
+        "@codemirror/language": "^6.0.0",
+        "@codemirror/lint": "^6.0.0",
+        "@codemirror/search": "^6.0.0",
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.0.0"
+      }
+    },
     "node_modules/color-convert": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
@@ -6232,6 +6446,12 @@
         }
       }
     },
+    "node_modules/crelt": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/crelt/-/crelt-1.0.6.tgz",
+      "integrity": "sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g==",
+      "license": "MIT"
+    },
     "node_modules/cross-fetch": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/cross-fetch/-/cross-fetch-4.0.0.tgz",
@@ -13598,6 +13818,12 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/style-mod": {
+      "version": "4.1.3",
+      "resolved": "https://registry.npmjs.org/style-mod/-/style-mod-4.1.3.tgz",
+      "integrity": "sha512-i/n8VsZydrugj3Iuzll8+x/00GH2vnYsk1eomD8QiRrSAeW6ItbCQDtfXCeJHd0iwiNagqjQkvpvREEPtW3IoQ==",
+      "license": "MIT"
+    },
     "node_modules/style-to-object": {
       "version": "0.3.0",
       "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-0.3.0.tgz",
@@ -14599,6 +14825,12 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/w3c-keyname": {
+      "version": "2.2.8",
+      "resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz",
+      "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==",
+      "license": "MIT"
+    },
     "node_modules/warn-once": {
       "version": "0.1.1",
       "resolved": "https://registry.npmjs.org/warn-once/-/warn-once-0.1.1.tgz",
diff --git a/client/package.json b/client/package.json
index 1603ff246..8d25ead0f 100644
--- a/client/package.json
+++ b/client/package.json
@@ -8,6 +8,7 @@
   "type": "module",
   "dependencies": {
     "@ant-design/v5-patch-for-react-19": "^1.0.3",
+    "@codemirror/lang-json": "^6.0.2",
     "@loadable/component": "^5.16.7",
     "@refinedev/antd": "^6.0.3",
     "@refinedev/core": "^5.0.7",
@@ -16,6 +17,7 @@
     "@refinedev/simple-rest": "^6.0.1",
     "@tanstack/react-query": "^5.90.16",
     "@tanstack/react-query-devtools": "^5.91.2",
+    "@uiw/react-codemirror": "^4.25.7",
     "@yudiel/react-qr-scanner": "^2.5.0",
     "axios": "^1.13.2",
     "dayjs": "^1.11.10",
@@ -39,19 +41,19 @@
     "@refinedev/cli": "^2.16.50",
     "@types/loadable__component": "^5.13.10",
     "@types/node": "^25.0.3",
-    "@types/react-dom": "^19.2.3",
     "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "@types/uuid": "^10.0.0",
     "@vitejs/plugin-react": "^5.1.2",
+    "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.26",
-    "eslint-plugin-react": "^7.37.5",
-    "eslint": "^9.39.2",
     "globals": "^17.0.0",
     "prettier": "3.7.4",
-    "typescript-eslint": "^8.52.0",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.52.0",
     "vite": "^7.3.0",
     "vite-plugin-mkcert": "^1.17.9",
     "vite-plugin-pwa": "^1.2.0"
diff --git a/client/public/locales/en/common.json b/client/public/locales/en/common.json
index 88ff2ae85..294ec7752 100644
--- a/client/public/locales/en/common.json
+++ b/client/public/locales/en/common.json
@@ -44,6 +44,7 @@
         "editError": "Error when editing {{resource}} (status code: {{statusCode}})",
         "importProgress": "Importing: {{processed}}/{{total}}",
         "saveSuccessful": "Save successful!",
+        "saveFailed": "Save failed.",
         "validationError": "Validation error: {{error}}"
     },
     "kofi": "Tip me on Ko-fi",
@@ -326,7 +327,13 @@
         },
         "extra_fields": {
             "tab": "Extra Fields",
-            "description": "<p>Here you can add extra custom fields to your entities.</p><p>Once a field is added, you can not change its key or type, and for choice type fields you can not remove choices or change the multi choice state. If you remove a field, the associated data for all entities will be deleted.</p><p>The key is what other programs read/write the data as, so if your custom field is supposed to integrate with a third-party program, make sure to set it correctly. Default value is only applied to new items.</p><p>Extra fields can not be sorted or filtered in the table views.</p>",
+            "top_guidance": "In all extra field types, the key is an integration identifier used by APIs and external tools, so choose stable names. Default values apply only to newly created items.",
+            "custom": {
+                "header": "Custom Extra Fields",
+                "description": "Custom extra fields are fields you define directly (text, number, datetime, choice, and ranges). In custom extra fields, key and type are immutable after creation. For choice fields, existing choices and the multi-choice mode are also immutable to protect stored data. Deleting a field removes its data from all records.",
+                "description_intro": "Custom extra fields are fields you define directly",
+                "description_immutability": "In custom extra fields, key and type are immutable after creation. For choice fields, existing choices and the multi-choice mode are also immutable to protect stored data. Deleting a field removes its data from all records."
+            },
             "params": {
                 "key": "Key",
                 "name": "Name",
@@ -353,7 +360,161 @@
             "non_unique_key_error": "The key must be unique.",
             "key_not_changed": "Please change the key to something else.",
             "delete_confirm": "Delete field {{name}}?",
-            "delete_confirm_description": "This will delete the field and all associated data for all entities."
+            "delete_confirm_description": "This will delete the field and all associated data for all entities.",
+            "delete_dependency_warning_intro": "Deleting this custom field will make dependent fields inoperable:",
+            "delete_dependency_warning_complex": "Complex extra fields: {{dependencies}}",
+            "delete_dependency_warning_formula": "Formula extra fields: {{dependencies}}",
+            "delete_dependency_warning_footer": "These entries remain saved, but behavior depending on this field will fail until references are updated."
+        },
+        "complex_fields": {
+            "tab": "Complex Extra Fields",
+            "intro": "Complex extra fields are optional app-provided feature modules that extend built-in and custom fields for this entity. They are enabled here when available.",
+            "table_note": "Complex extra field definitions are provided by installed feature modules and are not created from this page.",
+            "missing_references_intro": "Some complex extra fields reference custom fields that are no longer available.",
+            "missing_references": "Missing custom extra field references: {{references}}",
+            "description": "<p>Complex fields add optional, pre-defined behaviors beyond custom extra fields.</p><p>Enabling one can add specialized display, actions, calculated values, or list columns for the selected entity. Disabled features remain hidden so the standard UI stays simpler.</p><p>Each entry below states exactly what enabling it adds. This framework can stay empty until a specific advanced feature is installed.</p>",
+            "tooltip": "Complex extra fields are app-provided feature modules. Enabling one can add specialized display, actions, calculated values, or list columns for this entity.",
+            "help_links": {
+                "complex": "Help: Complex Extra Fields",
+                "formula": "Help: Formula Extra Fields",
+                "formula_json": "Help: JSON Logic",
+                "formula_tokens": "Help: Token Groups"
+            },
+            "empty": "No complex extra field feature modules are currently registered for this entity.",
+            "available_functions": {
+                "label": "Token categories:",
+                "value": "Operators, helper functions, and field references are grouped in the editor."
+            },
+            "columns": {
+                "name": "Name",
+                "description": "Feature",
+                "enable_description": "What Enabling Adds",
+                "surfaces": "Display In",
+                "enabled": "Enabled"
+            },
+            "surfaces": {
+                "show": "Show",
+                "edit": "Edit",
+                "list": "List",
+                "template": "Template",
+                "action": "Action",
+                "derived": "Derived"
+            },
+            "messages": {
+                "enabled": "Enabled {{name}}.",
+                "disabled": "Disabled {{name}}."
+            },
+            "formula": {
+                "header": "Formula Extra Fields",
+                "intro": "Formula extra fields are read-only derived values computed from expressions that reference existing fields.",
+                "evaluation_model_help": "Formula values are computed when records are loaded and are not stored as database columns. Dynamic helpers like today() refresh when data is reloaded.",
+                "description": "<p>Formula fields let you define your own calculated values for this entity.</p><p>Use references like <code>{weight}</code> or <code>{created_at}</code>, then combine them with math and helper functions. Formula fields are read-only and can be shown in list or show views.</p><p>This is where you can build calculations such as date parts, intervals, or specialized helpers like <code>hue_from_hex(...)</code>.</p>",
+                "tooltip": "Formula extra fields are user-defined calculated values. Use field references with the available formula functions to build read-only values for the selected display areas.",
+                "empty": "No formula fields are currently defined for this entity.",
+                "columns": {
+                    "key": "Key",
+                    "name": "Name",
+                    "description": "Description",
+                    "result_type": "Result Type",
+                    "expression": "Expression",
+                    "expression_json": "Expression JSON (JSON Logic)",
+                    "surfaces": "Display In",
+                    "allow_list_column_toggle": "Hide Columns Toggle",
+                    "include_in_api": "Include in API"
+                },
+                "types": {
+                    "number": "Number",
+                    "text": "Text"
+                },
+                "result_type_mismatch_hint": "Expression JSON appears to return {{inferred}}. You can keep the current type or auto-set it.",
+                "result_type_autoset": "Auto-set",
+                "tooltips": {
+                    "key": "Stable machine key for this formula field. It must be unique, uses lowercase letters/numbers/underscores, and is what later integrations will refer to.",
+                    "name": "Human-friendly label shown in the UI for this formula field.",
+                    "display_in": "Choose where this formula field is intended to appear later. Show means detail pages. List means table or list views. Template means label, title, or filename template variables.",
+                    "allow_list_column_toggle": "If enabled, list-display formula fields can be hidden or shown from the Hide Columns menu. If disabled, they stay visible whenever the field is shown in lists.",
+                    "include_in_api": "When enabled, this field can be included in API responses under payload.derived whenever include_derived is enabled for the request.",
+                    "expression_json": "JSON Logic object used to compute this formula field.",
+                    "sample_values": "Variable definition examples and formatting: {\"weight\": 1000, \"remaining_weight\": 225, \"created_at\": \"2026-02-28T10:15:00Z\", \"color_hex\": \"#FF00FF\"}"
+                },
+                "allow_list_column_toggle_help": "Only applies when List display is selected. This keeps optional formula columns discoverable in the existing Hide Columns picker.",
+                "allow_list_column_toggle_inline": "Enable column visibility in {{entity}} view.",
+                "sample_values": "Sample Values (JSON)",
+                "sample_values_help": "Define JSON variables for preview/testing of this expression.",
+                "expression_json_help": "Enter a JSON Logic object manually or using helper/reference tokens and operators to insert snippets.",
+                "expression_json_example": "Example: {\"-\": [{\"var\": \"weight\"}, {\"var\": \"remaining_weight\"}]}",
+                "expression_json_required": "Expression JSON (JSON Logic) is required.",
+                "key_usage_help": "API/template path",
+                "key_reserved_hint": "This key matches a formula token name ({{key}}). It still works, but choosing a distinct key can reduce confusion.",
+                "operator_groups": {
+                    "logical": "Logical / Conditional",
+                    "comparison": "Comparison",
+                    "arithmetic": "Arithmetic",
+                    "helpers": "Helpers"
+                },
+                "token_sections": {
+                    "operators": "Operators",
+                    "helper_functions": "Helper Functions"
+                },
+                "token_categories": {
+                    "logical": "Logical / Conditional",
+                    "comparison": "Comparison",
+                    "arithmetic": "Arithmetic",
+                    "math": "Math",
+                    "text": "Text",
+                    "datetime": "Date / Time",
+                    "dynamic": "Dynamic",
+                    "date_diff": "Date Diff",
+                    "color": "Color"
+                },
+                "reference_picker": {
+                    "label": "Field References",
+                    "placeholder": "Pick a field to insert into the expression",
+                    "help": "Tokens are clickable inserts. Helper Functions are functional tokens, and Field References insert {var} references for built-in or configured extra fields."
+                },
+                "json_builder": {
+                    "operators_title": "Insert Tokens",
+                    "click_to_insert_help": "Select a helper, then select compatible field references. Field references insert JSON snippets immediately. Use Helper only to insert placeholder arguments.",
+                    "pending_helper": "Pending reference for helper {{helper}} ({{selected}}/{{total}})",
+                    "pending_helper_prefix": "Pending reference for helper",
+                    "pending_helper_count": "({{selected}}/{{total}})",
+                    "helper_unavailable_reason": "Helper {{helper}} has no compatible references for this entity yet.",
+                    "helper_incompatible_reason": "Helper {{helper}} is incompatible with the currently selected pending reference type.",
+                    "reference_incompatible_reason": "Selected reference is incompatible with helper {{helper}}.",
+                    "show_operators": "Show operators",
+                    "hide_operators": "Hide operators",
+                    "operator_compact": {
+                        "logical_top": "Logical",
+                        "logical_bottom": "Conditional",
+                        "comparison": "Compare",
+                        "math": "Math"
+                    },
+                    "format": "Format JSON",
+                    "format_tooltip": "Normalizes and pretty-prints the current JSON in the editor.",
+                    "formatted": "Expression JSON formatted.",
+                    "insert_without_reference_tooltip": "Insert helper with placeholder inputs and clear pending selection.",
+                    "cancel_pending_tooltip": "Cancel pending helper selection.",
+                    "helper_only": "Helper only"
+                },
+                "delete_confirm": "Delete formula field {{name}}?",
+                "modal": {
+                    "create_title": "New Formula Extra Field",
+                    "edit_title": "Edit Formula Extra Field"
+                },
+                "messages": {
+                    "created": "Created {{name}}.",
+                    "updated": "Updated {{name}}.",
+                    "deleted": "Deleted {{name}}."
+                },
+                "missing_references_intro": "Some formula fields reference custom fields that are no longer available.",
+                "missing_references": "Missing custom field references: {{references}}",
+                "preview": {
+                    "button": "Preview Expression",
+                    "result_label": "Preview:",
+                    "references_used": "References used: {{references}}",
+                    "no_references": "No field references are used in this expression."
+                }
+            }
         }
     },
     "documentTitle": {
diff --git a/client/src/index.tsx b/client/src/index.tsx
index 75e4dcd06..06c084cc6 100644
--- a/client/src/index.tsx
+++ b/client/src/index.tsx
@@ -5,6 +5,28 @@ import { createRoot } from "react-dom/client";
 import App from "./App";
 import "./i18n";
 
+const LOCAL_CACHE_BYPASS_HOSTS = new Set(["localhost", "127.0.0.1"]);
+const shouldBypassLocalPwaCache = LOCAL_CACHE_BYPASS_HOSTS.has(window.location.hostname);
+
+if (shouldBypassLocalPwaCache) {
+  // Local PR validation should always reflect the newest bundle; clear service workers and
+  // their caches on localhost-style hosts to prevent stale UI from older test builds.
+  if ("serviceWorker" in navigator) {
+    void navigator.serviceWorker.getRegistrations().then((registrations) => {
+      registrations.forEach((registration) => {
+        void registration.unregister();
+      });
+    });
+  }
+  if ("caches" in window) {
+    void caches.keys().then((keys) => {
+      keys.forEach((key) => {
+        void caches.delete(key);
+      });
+    });
+  }
+}
+
 const container = document.getElementById("root") as HTMLElement;
 const root = createRoot(container);
 
diff --git a/client/src/pages/filaments/list.tsx b/client/src/pages/filaments/list.tsx
index 2d42198ce..fd05f9055 100644
--- a/client/src/pages/filaments/list.tsx
+++ b/client/src/pages/filaments/list.tsx
@@ -2,6 +2,7 @@ import { EditOutlined, EyeOutlined, FileOutlined, FilterOutlined, PlusSquareOutl
 import { List, useTable } from "@refinedev/antd";
 import { useInvalidate, useNavigation, useTranslate } from "@refinedev/core";
 import { Button, Dropdown, Table } from "antd";
+import { ColumnType } from "antd/es/table";
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc";
 import { useMemo, useState } from "react";
@@ -17,6 +18,7 @@ import {
   SpoolIconColumn,
 } from "../../components/column";
 import { useLiveify } from "../../components/liveify";
+import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import {
   useSpoolmanArticleNumbers,
   useSpoolmanFilamentNames,
@@ -24,8 +26,8 @@ import {
   useSpoolmanVendors,
 } from "../../components/otherModels";
 import { removeUndefined } from "../../utils/filtering";
-import { EntityType, useGetFields } from "../../utils/queryFields";
-import { TableState, useInitialTableState, useStoreInitialState } from "../../utils/saveload";
+import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
+import { TableState, useInitialTableState, useSavedState, useStoreInitialState } from "../../utils/saveload";
 import { useCurrencyFormatter } from "../../utils/settings";
 import { IFilament } from "./model";
 
@@ -33,6 +35,7 @@ dayjs.extend(utc);
 
 interface IFilamentCollapsed extends Omit<IFilament, "vendor"> {
   "vendor.name": string | null;
+  derived?: Record<string, unknown>;
 }
 
 function collapseFilament(element: IFilament): IFilamentCollapsed {
@@ -77,12 +80,13 @@ export const FilamentList = () => {
   const invalidate = useInvalidate();
   const navigate = useNavigate();
   const extraFields = useGetFields(EntityType.filament);
+  const formulaFields = useGetDerivedFields(EntityType.filament);
   const currencyFormatter = useCurrencyFormatter();
 
-  const allColumnsWithExtraFields = [...allColumns, ...(extraFields.data?.map((field) => "extra." + field.key) ?? [])];
-
   // Load initial state
   const initialState = useInitialTableState(namespace);
+  // Track formula-column hides separately so newly enabled toggleable fields still default to visible.
+  const [hiddenDerivedColumns, setHiddenDerivedColumns] = useSavedState<string[]>(`${namespace}-hiddenDerivedColumns`, []);
 
   // Fetch data from the API
   // To provide the live updates, we use a custom solution (useLiveify) instead of the built-in refine "liveMode" feature.
@@ -141,7 +145,41 @@ export const FilamentList = () => {
     () => (tableProps.dataSource || []).map((record) => ({ ...record })),
     [tableProps.dataSource],
   );
-  const dataSource = useLiveify("filament", queryDataSource, collapseFilament);
+  const liveDataSource = useLiveify("filament", queryDataSource, collapseFilament);
+  const listFormulaFields = useMemo(
+    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.list),
+    [formulaFields.data],
+  );
+  const toggleableListFormulaFields = useMemo(
+    () => listFormulaFields.filter((field) => field.allow_list_column_toggle),
+    [listFormulaFields],
+  );
+  const toggleableDerivedColumnKeys = useMemo(
+    () => toggleableListFormulaFields.map((field) => `derived.${field.key}`),
+    [toggleableListFormulaFields],
+  );
+  const allColumnsWithExtraFields = useMemo(
+    () => [
+      ...allColumns,
+      ...(extraFields.data?.map((field) => `extra.${field.key}`) ?? []),
+      ...toggleableDerivedColumnKeys,
+    ],
+    [extraFields.data, toggleableDerivedColumnKeys],
+  );
+  const selectedColumnKeys = useMemo(
+    () => [...showColumns, ...toggleableDerivedColumnKeys.filter((key) => !hiddenDerivedColumns.includes(key))],
+    [hiddenDerivedColumns, showColumns, toggleableDerivedColumnKeys],
+  );
+  const dataSource = useMemo<IFilamentCollapsed[]>(
+    () =>
+      liveDataSource.map((record) => ({
+        ...record,
+        // Formula values are computed client-side from the fetched row and are not persisted
+        // server-side fields, so they update on reload/live row updates and remain display-only.
+        derived: buildFormulaValues(record, listFormulaFields),
+      })),
+    [liveDataSource, listFormulaFields],
+  );
 
   if (tableProps.pagination) {
     tableProps.pagination.showSizeChanger = true;
@@ -165,6 +203,11 @@ export const FilamentList = () => {
     sorter: true,
   };
 
+  const updateColumnSelections = (selectedKeys: string[]) => {
+    setShowColumns(selectedKeys.filter((key) => !toggleableDerivedColumnKeys.includes(key)));
+    setHiddenDerivedColumns(toggleableDerivedColumnKeys.filter((key) => !selectedKeys.includes(key)));
+  };
+
   return (
     <List
       headerButtons={({ defaultButtons }) => (
@@ -191,20 +234,27 @@ export const FilamentList = () => {
                     label: extraField?.name ?? column_id,
                   };
                 }
+                if (column_id.indexOf("derived.") === 0) {
+                  const formulaField = toggleableListFormulaFields.find((field) => `derived.${field.key}` === column_id);
+                  return {
+                    key: column_id,
+                    label: formulaField?.name ?? column_id,
+                  };
+                }
 
                 return {
                   key: column_id,
                   label: t(translateColumnI18nKey(column_id)),
                 };
               }),
-              selectedKeys: showColumns,
+              selectedKeys: selectedColumnKeys,
               selectable: true,
               multiple: true,
               onDeselect: (keys) => {
-                setShowColumns(keys.selectedKeys);
+                updateColumnSelections(keys.selectedKeys.map(String));
               },
               onSelect: (keys) => {
-                setShowColumns(keys.selectedKeys);
+                updateColumnSelections(keys.selectedKeys.map(String));
               },
             }}
           >
@@ -335,6 +385,21 @@ export const FilamentList = () => {
               field,
             });
           }) ?? []),
+          ...listFormulaFields.map(
+            (field) => {
+              const derivedColumnKey = `derived.${field.key}`;
+              if (field.allow_list_column_toggle && hiddenDerivedColumns.includes(derivedColumnKey)) {
+                return undefined;
+              }
+
+              return {
+                key: derivedColumnKey,
+                title: field.name,
+                width: 140,
+                render: (_: unknown, record: IFilamentCollapsed) => formatFormulaValue(record.derived?.[field.key]),
+              } as ColumnType<IFilamentCollapsed>;
+            },
+          ),
           RichColumn({
             ...commonProps,
             id: "comment",
diff --git a/client/src/pages/filaments/show.tsx b/client/src/pages/filaments/show.tsx
index 4bc6c66be..4c98fe19d 100644
--- a/client/src/pages/filaments/show.tsx
+++ b/client/src/pages/filaments/show.tsx
@@ -1,3 +1,4 @@
+import { Fragment, useMemo } from "react";
 import { DateField, NumberField, Show, TextField } from "@refinedev/antd";
 import { useShow, useTranslate } from "@refinedev/core";
 import { Button, Typography } from "antd";
@@ -7,8 +8,9 @@ import { useNavigate } from "react-router";
 import { ExtraFieldDisplay } from "../../components/extraFields";
 import { NumberFieldUnit } from "../../components/numberField";
 import SpoolIcon from "../../components/spoolIcon";
+import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import { enrichText } from "../../utils/parsing";
-import { EntityType, useGetFields } from "../../utils/queryFields";
+import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { useCurrencyFormatter } from "../../utils/settings";
 import { IFilament } from "./model";
 dayjs.extend(utc);
@@ -19,6 +21,7 @@ export const FilamentShow = () => {
   const t = useTranslate();
   const navigate = useNavigate();
   const extraFields = useGetFields(EntityType.filament);
+  const formulaFields = useGetDerivedFields(EntityType.filament);
   const currencyFormatter = useCurrencyFormatter();
   const { query } = useShow<IFilament>({
     liveMode: "auto",
@@ -26,6 +29,14 @@ export const FilamentShow = () => {
   const { data, isLoading } = query;
 
   const record = data?.data;
+  const showFormulaFields = useMemo(
+    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.show),
+    [formulaFields.data],
+  );
+  const derivedValues = useMemo(
+    () => (record ? buildFormulaValues(record, showFormulaFields) : {}),
+    [record, showFormulaFields],
+  );
 
   const formatTitle = (item: IFilament) => {
     let vendorPrefix = "";
@@ -151,6 +162,13 @@ export const FilamentShow = () => {
       {extraFields?.data?.map((field, index) => (
         <ExtraFieldDisplay key={index} field={field} value={record?.extra[field.key]} />
       ))}
+      {showFormulaFields.length > 0 && <Title level={4}>{t("settings.complex_fields.formula.header")}</Title>}
+      {showFormulaFields.map((field) => (
+        <Fragment key={field.key}>
+          <Title level={5}>{field.name}</Title>
+          <TextField value={formatFormulaValue(derivedValues[field.key])} />
+        </Fragment>
+      ))}
     </Show>
   );
 };
diff --git a/client/src/pages/help/index.tsx b/client/src/pages/help/index.tsx
index bf493e6fd..3ee37bc86 100644
--- a/client/src/pages/help/index.tsx
+++ b/client/src/pages/help/index.tsx
@@ -1,27 +1,169 @@
 import { FileOutlined, HighlightOutlined, UserOutlined } from "@ant-design/icons";
 import { useTranslate } from "@refinedev/core";
-import { List, theme } from "antd";
+import { Button, Col, Divider, Flex, List, Modal, Row, Space, Table, Tooltip, Typography, theme } from "antd";
 import { Content } from "antd/es/layout/layout";
+import { ColumnsType } from "antd/es/table";
 import Title from "antd/es/typography/Title";
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc";
+import { useEffect, useMemo, useState } from "react";
 import { Trans } from "react-i18next";
-import { Link } from "react-router";
+import { Link, useLocation } from "react-router";
+import { FORMULA_HELPER_GROUPS } from "../../utils/formulaFields";
 
 dayjs.extend(utc);
 
 const { useToken } = theme;
+const { Paragraph, Text } = Typography;
+
+type BuiltInEntity = "spool" | "filament" | "vendor";
+
+type BuiltInFieldDefinition = {
+  key: string;
+  type: "text" | "integer" | "integer_range" | "float" | "float_range" | "datetime" | "boolean" | "choice";
+  intent: string;
+};
+
+const BUILT_IN_FIELD_DEFINITIONS: Record<BuiltInEntity, BuiltInFieldDefinition[]> = {
+  spool: [
+    { key: "id", type: "integer", intent: "Stable system identifier for this spool record." },
+    { key: "registered", type: "datetime", intent: "UTC timestamp for when the spool was first created in Spoolman." },
+    { key: "first_used", type: "datetime", intent: "UTC timestamp of the first tracked filament usage event on this spool." },
+    { key: "last_used", type: "datetime", intent: "UTC timestamp of the most recent tracked usage event on this spool." },
+    { key: "filament", type: "choice", intent: "Linked filament profile this physical spool belongs to." },
+    { key: "price", type: "float", intent: "Effective price for this spool, used for cost tracking and reporting." },
+    { key: "initial_weight", type: "float", intent: "Starting net filament weight for this specific spool instance." },
+    { key: "spool_weight", type: "float", intent: "Empty spool weight override used for measured-weight calculations." },
+    { key: "remaining_weight", type: "float", intent: "Current estimated net filament remaining on the spool." },
+    { key: "used_weight", type: "float", intent: "Current estimated net filament consumed from the spool." },
+    { key: "remaining_length", type: "float", intent: "Current estimated filament length remaining on the spool." },
+    { key: "used_length", type: "float", intent: "Current estimated filament length consumed from the spool." },
+    { key: "location", type: "text", intent: "Storage or printer location label for organizing spool inventory." },
+    { key: "lot_nr", type: "text", intent: "Manufacturer lot identifier used for traceability and color consistency." },
+    { key: "comment", type: "text", intent: "Free-form operator notes for this spool." },
+    { key: "archived", type: "boolean", intent: "Archive status flag used to hide inactive spools from normal workflows." },
+  ],
+  filament: [
+    { key: "id", type: "integer", intent: "Stable system identifier for this filament profile." },
+    { key: "registered", type: "datetime", intent: "UTC timestamp for when the filament profile was created." },
+    { key: "name", type: "text", intent: "Human-readable filament product name." },
+    { key: "vendor", type: "choice", intent: "Linked manufacturer profile for this filament." },
+    { key: "material", type: "text", intent: "Base material category such as PLA, PETG, ABS, or similar." },
+    { key: "price", type: "float", intent: "Reference price for a full spool of this filament profile." },
+    { key: "density", type: "float", intent: "Material density used for weight/length conversion math." },
+    { key: "diameter", type: "float", intent: "Nominal filament diameter used for volume and length calculations." },
+    { key: "weight", type: "float", intent: "Nominal net filament weight for a full spool." },
+    { key: "spool_weight", type: "float", intent: "Nominal empty spool weight for measured-weight workflows." },
+    { key: "article_number", type: "text", intent: "External catalog code such as SKU, UPC, or EAN." },
+    { key: "settings_extruder_temp", type: "integer", intent: "Reference nozzle temperature for print profile setup." },
+    { key: "settings_bed_temp", type: "integer", intent: "Reference bed temperature for print profile setup." },
+    { key: "color_hex", type: "text", intent: "Primary hex color used for UI display and swatches." },
+    { key: "multi_color_hexes", type: "text", intent: "Hex color list for multi-color filament definitions." },
+    { key: "multi_color_direction", type: "choice", intent: "Multi-color layout mode, such as coextruded or longitudinal." },
+    { key: "external_id", type: "text", intent: "Provider-specific identifier for external filament databases." },
+    { key: "comment", type: "text", intent: "Free-form notes about this filament profile." },
+  ],
+  vendor: [
+    { key: "id", type: "integer", intent: "Stable system identifier for this manufacturer profile." },
+    { key: "registered", type: "datetime", intent: "UTC timestamp for when the manufacturer profile was created." },
+    { key: "name", type: "text", intent: "Manufacturer name used across linked filament profiles." },
+    { key: "empty_spool_weight", type: "float", intent: "Default empty spool weight for this manufacturer." },
+    { key: "external_id", type: "text", intent: "Provider-specific identifier for external manufacturer databases." },
+    { key: "comment", type: "text", intent: "Free-form notes about this manufacturer profile." },
+  ],
+};
+const JSON_OPERATOR_GROUPS: Array<{ label: string; operators: string[] }> = [
+  { label: "Logical / Conditional", operators: ["if", "and", "or", "!"] },
+  { label: "Comparison", operators: ["==", "!=", "<", "<=", ">", ">="] },
+  { label: "Arithmetic", operators: ["+", "-", "*", "/", "%"] },
+];
 
 export const Help = () => {
   const { token } = useToken();
   const t = useTranslate();
+  const location = useLocation();
+  const [builtInFieldEntity, setBuiltInFieldEntity] = useState<BuiltInEntity | null>(null);
+  const sectionBodyStyle = { fontSize: token.fontSize, lineHeight: 1.7 };
+  const nestedLevel4Style = { marginLeft: 16 };
+  const nestedLevel5Style = { marginLeft: 28 };
+  const nestedLevel6Style = { marginLeft: 40 };
+
+  const renderLevel3Heading = (title: string, marginTop = 0) => (
+    <Flex align="center" gap={12} style={{ marginTop, marginBottom: 8 }}>
+      <Title level={3} style={{ margin: 0 }}>
+        {title}
+      </Title>
+      <div style={{ flex: 1, borderBottom: `1px solid ${token.colorBorderSecondary}` }} />
+    </Flex>
+  );
+
+  const builtInFieldRows = useMemo(() => {
+    if (!builtInFieldEntity) {
+      return [];
+    }
+    return BUILT_IN_FIELD_DEFINITIONS[builtInFieldEntity];
+  }, [builtInFieldEntity]);
+
+  useEffect(() => {
+    if (!location.hash) {
+      return;
+    }
+
+    const targetId = decodeURIComponent(location.hash.replace(/^#/, ""));
+    const scrollToTarget = () => {
+      const target = document.getElementById(targetId);
+      if (target) {
+        target.scrollIntoView({ behavior: "smooth", block: "start" });
+      }
+    };
+
+    // Route transitions can render asynchronously; run once immediately and once shortly after.
+    const animationFrame = requestAnimationFrame(scrollToTarget);
+    const timeout = window.setTimeout(scrollToTarget, 180);
+    return () => {
+      cancelAnimationFrame(animationFrame);
+      window.clearTimeout(timeout);
+    };
+  }, [location.hash]);
+
+  const builtInFieldColumns: ColumnsType<{ key: string; type: string; intent: string }> = [
+    {
+      title: "Field",
+      dataIndex: "key",
+      key: "field",
+      width: "24%",
+      render: (value: string) => <Text code>{value}</Text>,
+    },
+    {
+      title: "Type",
+      dataIndex: "type",
+      key: "type",
+      width: "18%",
+      render: (value: string) => <Text code>{value}</Text>,
+    },
+    {
+      title: "Intent",
+      dataIndex: "intent",
+      key: "intent",
+      render: (value: string) => <Text type="secondary">{value}</Text>,
+    },
+  ];
+
+  const builtInFieldEntityTitle =
+    builtInFieldEntity === "spool"
+      ? "Spool"
+      : builtInFieldEntity === "filament"
+        ? "Filament"
+        : builtInFieldEntity === "vendor"
+          ? "Manufacturer"
+          : "";
 
   return (
     <Content
       style={{
         padding: 20,
         minHeight: 280,
-        maxWidth: 1000,
+        maxWidth: 1200,
         margin: "0 auto",
         backgroundColor: token.colorBgContainer,
         borderRadius: token.borderRadiusLG,
@@ -70,6 +212,331 @@ export const Help = () => {
           ),
         }}
       />
+      <Divider />
+      <Title level={2} style={{ marginBottom: 8 }}>
+        Field Overview
+      </Title>
+      <Paragraph type="secondary" style={sectionBodyStyle}>
+        Spoolman includes built-in fields per entity and supports two extra field types:{" "}
+        <Text strong>Custom Extra Fields</Text> and <Text strong>Formula Extra Fields</Text>.
+      </Paragraph>
+      <section id="built-in-fields">
+        {renderLevel3Heading("Built-in Fields")}
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel4Style }}>
+          Built-in fields are core Spoolman attributes used by default forms, list columns, APIs, and label/template
+          references.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel4Style, marginBottom: 0 }}>
+          Open a quick field map:
+        </Paragraph>
+        <Flex gap={8} wrap style={{ ...nestedLevel4Style, marginTop: 8 }}>
+          <Button size="small" onClick={() => setBuiltInFieldEntity("spool")}>
+            Spool
+          </Button>
+          <Button size="small" onClick={() => setBuiltInFieldEntity("filament")}>
+            Filament
+          </Button>
+          <Button size="small" onClick={() => setBuiltInFieldEntity("vendor")}>
+            Manufacturer
+          </Button>
+        </Flex>
+      </section>
+      <Modal
+        title={builtInFieldEntity ? `${builtInFieldEntityTitle} Built-in Fields` : undefined}
+        open={builtInFieldEntity !== null}
+        footer={null}
+        onCancel={() => setBuiltInFieldEntity(null)}
+        width={900}
+      >
+        <Table
+          size="small"
+          pagination={false}
+          columns={builtInFieldColumns}
+          dataSource={builtInFieldRows}
+          rowKey="key"
+          scroll={{ y: 420 }}
+        />
+      </Modal>
+      <section id="extra-fields">
+        {renderLevel3Heading("Extra Fields", 24)}
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel4Style }}>
+          Extra fields let you store additional data directly and define user-maintained derived values across
+          entities.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel4Style }}>
+          Configure definitions in{" "}
+          <Link to="/settings/extra/spool">Settings → Extra Fields → Spools</Link>,{" "}
+          <Link to="/settings/extra/filament">Filaments</Link>, and{" "}
+          <Link to="/settings/extra/vendor">Manufacturers</Link>.
+        </Paragraph>
+      </section>
+      <section id="custom-extra-fields">
+        <Title level={4} style={{ marginTop: 24, marginBottom: 8, ...nestedLevel4Style }}>
+          Custom Extra Fields
+        </Title>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          Custom extra fields store direct values that you enter or import for each entity record.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          Supported types include <Text code>text</Text>, <Text code>integer</Text>, <Text code>integer_range</Text>,{" "}
+          <Text code>float</Text>, <Text code>float_range</Text>, <Text code>datetime</Text>,{" "}
+          <Text code>boolean</Text>, and <Text code>choice</Text>.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          In custom extra fields, key and type are immutable after creation. For choice fields, existing choices and
+          the multi-choice mode are also immutable. Deleting a field removes its data from all records.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          Keys should stay stable because APIs and integrations use them as identifiers. Default values apply only to
+          newly created items.
+        </Paragraph>
+      </section>
+      <section id="formula-fields">
+        <Title level={4} style={{ marginTop: 24, marginBottom: 8, ...nestedLevel4Style }}>
+          Formula Extra Fields
+        </Title>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          Formula extra fields turn existing built-in/custom data into calculated values you can reuse everywhere.
+          Common examples are spool age, normalized date labels, cost deltas, and short text tags.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          They are read-only outputs configured per entity, so source records stay unchanged. The primary authoring
+          format is <Text code>Expression JSON (JSON Logic)</Text>.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          Configure them in <Link to="/settings/extra/spool">Settings → Extra Fields</Link> for Spools, Filaments, or
+          Manufacturers. In <Text strong>Formula Extra Fields</Text>, click <Text code>+</Text>, build your JSON
+          expression, then validate with <Text code>Sample Values (JSON)</Text> and <Text code>Preview Expression</Text>{" "}
+          before saving.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          In each formula field editor, use <Text strong>Include in API</Text> to mark that field as eligible for API
+          output. Entity responses include only those field-level opt-ins under a <Text code>derived</Text> object
+          whenever <Text code>include_derived=true</Text> is requested. Each field key is exposed as{" "}
+          <Text code>{`derived.<key>`}</Text>.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          Formula values are computed when records are loaded and are not stored as dedicated database columns. Dynamic
+          helpers such as <Text code>today()</Text> refresh when data is reloaded. Enabling API derived output can add
+          response compute time on large lists. Per request, clients can override the default with{" "}
+          <Text code>include_derived=true</Text> or <Text code>include_derived=false</Text>.
+        </Paragraph>
+        <Title id="formula-json-logic" level={5} style={{ marginTop: 0, marginBottom: 8, ...nestedLevel5Style }}>
+          JSON Logic
+        </Title>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          Token groups are clickable inserts that speed up authoring and reduce JSON syntax mistakes.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          <Text strong>Field References</Text> insert JSON Logic variable objects. For example,{" "}
+          <Text code>{`{weight}`}</Text> inserts <Text code>{`{"var":"weight"}`}</Text> and{" "}
+          <Text code>{`{extra.purchase_date}`}</Text> inserts <Text code>{`{"var":"extra.purchase_date"}`}</Text>.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          <Text strong>Operators</Text> insert operator templates, and <Text strong>Helper Functions</Text> insert
+          helper templates that can be completed with compatible field references.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          Helper insertion is staged: click a helper first, then click the required compatible references. While a
+          helper is pending, incompatible helper/reference tokens are visible but dimmed. Use <Text code>X</Text> to
+          cancel pending helper selection, or <Text code>Helper only</Text> to insert that helper with placeholder
+          inputs.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          Formula-to-formula references are not supported. Build nested JSON Logic in a single formula instead of
+          referencing another formula field. Formula outputs are available in API/template usage via{" "}
+          <Text code>{`derived.<key>`}</Text>.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          On wider layouts, operators are shown in a right-side panel next to the JSON editor and can be collapsed or
+          expanded. On narrow layouts, operators are hidden from the panel and can still be entered directly in JSON.
+        </Paragraph>
+        <Row gutter={[16, 16]} align="top" style={nestedLevel6Style}>
+          <Col xs={24} xl={12}>
+            <Title id="formula-token-groups" level={5} style={{ marginTop: 0, marginBottom: 8 }}>
+              Token Groups
+            </Title>
+            <div
+              style={{
+                border: `1px solid ${token.colorBorderSecondary}`,
+                borderRadius: token.borderRadiusLG,
+                padding: 12,
+                background: token.colorBgContainer,
+              }}
+            >
+              <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginBottom: 10 }}>
+                Operators
+              </Paragraph>
+              <Row gutter={[8, 8]}>
+                {JSON_OPERATOR_GROUPS.map((group) => (
+                  <Col xs={24} md={8} key={group.label}>
+                    <div
+                      style={{
+                        border: `1px solid ${token.colorBorderSecondary}`,
+                        borderRadius: token.borderRadius,
+                        padding: 8,
+                        minHeight: 84,
+                      }}
+                    >
+                      <Text strong>{group.label}</Text>
+                      <div style={{ marginTop: 6 }}>
+                        <Space size={[4, 4]} wrap>
+                          {group.operators.map((operator) => (
+                            <Text key={operator} code>
+                              {operator}
+                            </Text>
+                          ))}
+                        </Space>
+                      </div>
+                    </div>
+                  </Col>
+                ))}
+              </Row>
+              <Divider style={{ margin: "12px 0" }} />
+              <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginBottom: 10 }}>
+                Helper Functions
+              </Paragraph>
+              <Row gutter={[8, 8]}>
+                {FORMULA_HELPER_GROUPS.map((group) => (
+                  <Col xs={24} md={12} key={group.key}>
+                    <div
+                      style={{
+                        border: `1px solid ${token.colorBorderSecondary}`,
+                        borderRadius: token.borderRadius,
+                        padding: 8,
+                      }}
+                    >
+                      <Text strong>{t(`settings.complex_fields.formula.token_categories.${group.key}`)}</Text>
+                      <div style={{ marginTop: 6 }}>
+                        <Space size={[4, 4]} wrap>
+                          {group.helpers.map((helper) => (
+                            <Tooltip key={helper.name} title={helper.description}>
+                              <Text code>{helper.name}</Text>
+                            </Tooltip>
+                          ))}
+                        </Space>
+                      </div>
+                    </div>
+                  </Col>
+                ))}
+              </Row>
+            </div>
+          </Col>
+          <Col xs={24} xl={12}>
+            <Title level={5} style={{ marginTop: 0, marginBottom: 8 }}>
+              Concrete Examples
+            </Title>
+            <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginBottom: 12 }}>
+              Variables come from available field references for the selected entity, including built-in fields
+              (for example <Text code>{`{created_at}`}</Text>) and custom fields
+              (for example <Text code>{`{extra.purchase_date}`}</Text>).
+            </Paragraph>
+            <Space direction="vertical" size={10} style={{ width: "100%" }}>
+              <div
+                style={{
+                  border: `1px solid ${token.colorBorderSecondary}`,
+                  borderRadius: token.borderRadius,
+                  padding: 10,
+                }}
+              >
+                <Text strong>Example 1: Full timestamp to YYYY-MM-DD</Text>
+                <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 6 }}>
+                  Variable definitions:
+                </Paragraph>
+                <Text code>{`{"created_at":"2026-03-09T14:23:45Z"}`}</Text>
+                <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 6 }}>
+                  Expression JSON:
+                </Paragraph>
+                <Text code>{`{"date_only":[{"var":"created_at"}]}`}</Text>
+                <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 0 }}>
+                  Result: <Text code>{`"2026-03-09"`}</Text>
+                </Paragraph>
+              </div>
+              <div
+                style={{
+                  border: `1px solid ${token.colorBorderSecondary}`,
+                  borderRadius: token.borderRadius,
+                  padding: 10,
+                }}
+              >
+                <Text strong>Example 2: Difference between two datetimes</Text>
+                <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 6 }}>
+                  Variable definitions:
+                </Paragraph>
+                <Text code>{`{"first_used":"2026-03-01T10:00:00Z","last_used":"2026-03-09T16:00:00Z"}`}</Text>
+                <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 6 }}>
+                  Expression JSON:
+                </Paragraph>
+                <Text code>{`{"days_between":[{"var":"first_used"},{"var":"last_used"}]}`}</Text>
+                <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 0 }}>
+                  Result: <Text code>{`8.25`}</Text>
+                </Paragraph>
+              </div>
+              <div
+                style={{
+                  border: `1px solid ${token.colorBorderSecondary}`,
+                  borderRadius: token.borderRadius,
+                  padding: 10,
+                }}
+              >
+                <Text strong>Example 3: Short text label from lot number</Text>
+                <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 6 }}>
+                  Variable definitions:
+                </Paragraph>
+                <Text code>{`{"lot_nr":"ABCD-23991"}`}</Text>
+                <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 6 }}>
+                  Expression JSON:
+                </Paragraph>
+                <Text code>{`{"left":[{"var":"lot_nr"},4]}`}</Text>
+                <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 0 }}>
+                  Result: <Text code>{`"ABCD"`}</Text>
+                </Paragraph>
+              </div>
+            </Space>
+          </Col>
+        </Row>
+        <Title level={5} style={{ marginTop: 0, marginBottom: 8, ...nestedLevel6Style }}>
+          Formatting & Validation
+        </Title>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          The expression editor uses a JSON code editor (CodeMirror). Use <Text code>Format JSON</Text> to
+          auto-pretty-print your JSON Logic object. Keep <Text code>Preview Expression</Text> +{" "}
+          <Text code>Sample Values (JSON)</Text> as your first validation pass.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          <Text code>Sample Values (JSON)</Text> must be a valid JSON object used only for preview/testing. Use plain
+          keys without braces, and match keys to your <Text code>{`{"var":"..."}`}</Text> references. Example:{" "}
+          <Text code>{`{"weight": 1000, "remaining_weight": 225, "created_at": "2026-02-28T10:15:00Z", "color_hex": "#FF00FF"}`}</Text>.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          Reference docs:{" "}
+          <a href="https://jsonlogic.com/" target="_blank" rel="noreferrer">
+            jsonlogic.com
+          </a>
+          {" · "}
+          <a href="https://jsonlogic.com/operations.html" target="_blank" rel="noreferrer">
+            operations
+          </a>
+          {" · "}
+          <a href="https://jsonlint.com/" target="_blank" rel="noreferrer">
+            JSONLint
+          </a>
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          Choose where each formula appears: <Text code>Show</Text> (record details), <Text code>List</Text>{" "}
+          (table/list pages), and <Text code>Template</Text> (label/title/filename templates).
+        </Paragraph>
+        <ul style={{ margin: "0 0 16px 56px", color: token.colorTextSecondary, lineHeight: 1.7, fontSize: token.fontSize }}>
+          <li>
+            If a formula includes <Text code>List</Text>, you can enable column toggling so it can be hidden or shown
+            through <Text code>Hide Columns</Text> on list pages.
+          </li>
+          <li>
+            If a formula includes <Text code>Template</Text>, it can be referenced in templates as{" "}
+            <Text code>{`{derived.your_key}`}</Text> (for example, <Text code>{`{derived.days_between_events}`}</Text>).
+          </li>
+        </ul>
+      </section>
     </Content>
   );
 };
diff --git a/client/src/pages/printing/spoolQrCodePrintingDialog.tsx b/client/src/pages/printing/spoolQrCodePrintingDialog.tsx
index 865c597cf..b3f9ab366 100644
--- a/client/src/pages/printing/spoolQrCodePrintingDialog.tsx
+++ b/client/src/pages/printing/spoolQrCodePrintingDialog.tsx
@@ -4,7 +4,8 @@ import { Button, Flex, Form, Input, Modal, Popconfirm, Select, Table, Typography
 import TextArea from "antd/es/input/TextArea";
 import { useState } from "react";
 import { v4 as uuidv4 } from "uuid";
-import { EntityType, useGetFields } from "../../utils/queryFields";
+import { buildFormulaValues, getTemplateFormulaFields } from "../../utils/formulaFields";
+import { EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { useGetSetting } from "../../utils/querySettings";
 import { useSavedState } from "../../utils/saveload";
 import { useGetSpoolsByIds } from "../spools/functions";
@@ -182,11 +183,15 @@ Spool Weight: {filament.spool_weight} g
     { tag: "archived" },
   ];
   const spoolFields = useGetFields(EntityType.spool);
+  const spoolDerivedFields = useGetDerivedFields(EntityType.spool);
   if (spoolFields.data !== undefined) {
     spoolFields.data.forEach((field) => {
       spoolTags.push({ tag: `extra.${field.key}` });
     });
   }
+  getTemplateFormulaFields(spoolDerivedFields.data).forEach((field) => {
+    spoolTags.push({ tag: `derived.${field.key}` });
+  });
   const filamentTags = [
     { tag: "filament.id" },
     { tag: "filament.registered" },
@@ -207,11 +212,15 @@ Spool Weight: {filament.spool_weight} g
     { tag: "filament.external_id" },
   ];
   const filamentFields = useGetFields(EntityType.filament);
+  const filamentDerivedFields = useGetDerivedFields(EntityType.filament);
   if (filamentFields.data !== undefined) {
     filamentFields.data.forEach((field) => {
       filamentTags.push({ tag: `filament.extra.${field.key}` });
     });
   }
+  getTemplateFormulaFields(filamentDerivedFields.data).forEach((field) => {
+    filamentTags.push({ tag: `filament.derived.${field.key}` });
+  });
   const vendorTags = [
     { tag: "filament.vendor.id" },
     { tag: "filament.vendor.registered" },
@@ -221,14 +230,44 @@ Spool Weight: {filament.spool_weight} g
     { tag: "filament.vendor.external_id" },
   ];
   const vendorFields = useGetFields(EntityType.vendor);
+  const vendorDerivedFields = useGetDerivedFields(EntityType.vendor);
   if (vendorFields.data !== undefined) {
     vendorFields.data.forEach((field) => {
       vendorTags.push({ tag: `filament.vendor.extra.${field.key}` });
     });
   }
+  getTemplateFormulaFields(vendorDerivedFields.data).forEach((field) => {
+    vendorTags.push({ tag: `filament.vendor.derived.${field.key}` });
+  });
 
   const templateTags = [...spoolTags, ...filamentTags, ...vendorTags];
 
+  const templateReadySpools = items.map((spool) => {
+    const filament = spool.filament;
+    const vendor = filament.vendor;
+
+    const spoolDerived = buildFormulaValues(spool, getTemplateFormulaFields(spoolDerivedFields.data));
+    const filamentDerived = buildFormulaValues(filament, getTemplateFormulaFields(filamentDerivedFields.data));
+    const vendorDerived = vendor
+      ? buildFormulaValues(vendor, getTemplateFormulaFields(vendorDerivedFields.data))
+      : {};
+
+    return {
+      ...spool,
+      derived: spoolDerived,
+      filament: {
+        ...filament,
+        derived: filamentDerived,
+        vendor: vendor
+          ? {
+              ...vendor,
+              derived: vendorDerived,
+            }
+          : vendor,
+      },
+    };
+  });
+
   return (
     <>
       {contextHolder}
@@ -299,7 +338,7 @@ Spool Weight: {filament.spool_weight} g
             </Form.Item>
           </>
         }
-        items={items.map((spool) => ({
+        items={templateReadySpools.map((spool) => ({
           value: useHTTPUrl ? `${baseUrlRoot}/spool/show/${spool.id}` : `WEB+SPOOLMAN:S-${spool.id}`,
           label: (
             <p
diff --git a/client/src/pages/settings/complexFieldsSettings.tsx b/client/src/pages/settings/complexFieldsSettings.tsx
new file mode 100644
index 000000000..0b95cac35
--- /dev/null
+++ b/client/src/pages/settings/complexFieldsSettings.tsx
@@ -0,0 +1,1834 @@
+import { json } from "@codemirror/lang-json";
+import { EditorView, drawSelection } from "@codemirror/view";
+import CodeMirror from "@uiw/react-codemirror";
+import {
+  CloseCircleOutlined,
+  MenuFoldOutlined,
+  MenuUnfoldOutlined,
+  PlusOutlined,
+  QuestionCircleOutlined,
+  WarningOutlined,
+} from "@ant-design/icons";
+import { useTranslate } from "@refinedev/core";
+import {
+  Button,
+  Col,
+  Divider,
+  Empty,
+  Flex,
+  Form,
+  Grid,
+  Input,
+  Modal,
+  Popconfirm,
+  Row,
+  Select,
+  Space,
+  Switch,
+  Table,
+  Tag,
+  Tooltip,
+  Typography,
+  message,
+  theme,
+} from "antd";
+import { ColumnType } from "antd/es/table";
+import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from "react";
+import { Link, useParams } from "react-router";
+import {
+  FORMULA_HELPER_GROUPS,
+  FORMULA_HELPERS,
+  FormulaHelperDefinition,
+  getExtraFieldReferences,
+} from "../../utils/formulaFields";
+import {
+  ComplexFieldSurface,
+  DerivedField,
+  DerivedFieldType,
+  EntityType,
+  FieldType,
+  useDeleteDerivedField,
+  useGetDerivedFields,
+  useGetFields,
+  usePreviewDerivedField,
+  useSetDerivedField,
+} from "../../utils/queryFields";
+
+const DERIVED_SURFACE_OPTIONS = [ComplexFieldSurface.show, ComplexFieldSurface.list, ComplexFieldSurface.template];
+const BUILTIN_REFERENCE_SUGGESTIONS: Record<EntityType, string[]> = {
+  vendor: ["id", "name", "registered", "comment"],
+  filament: ["id", "name", "material", "price", "density", "weight", "color_hex", "comment"],
+  spool: ["id", "weight", "remaining_weight", "used_weight", "price", "lot_nr", "comment", "created_at"],
+};
+const SAMPLE_VALUE_PLACEHOLDERS: Record<EntityType, string> = {
+  vendor: '{"name": "Example Vendor", "registered": "2026-02-28T10:15:00Z"}',
+  filament: '{"weight": 1000, "material": "PLA", "created_at": "2026-02-28T10:15:00Z", "color_hex": "#FF00FF"}',
+  spool: '{"weight": 1000, "remaining_weight": 225, "created_at": "2026-02-28T10:15:00Z"}',
+};
+const JSON_LOGIC_OPERATOR_GROUPS: Array<{ key: string; operators: string[] }> = [
+  { key: "logical", operators: ["if", "and", "or", "!"] },
+  { key: "comparison", operators: ["==", "!=", "<", "<=", ">", ">="] },
+  { key: "arithmetic", operators: ["+", "-", "*", "/", "%"] },
+];
+const OPERATOR_PANEL_WIDTH = 244;
+const INLINE_OPERATOR_PANEL_HEIGHT = 264;
+const HELPER_DESKTOP_COLUMN_LAYOUT: Array<{ top: string; bottom?: string }> = [
+  { top: "math", bottom: "color" },
+  { top: "text" },
+  { top: "datetime" },
+  { top: "dynamic", bottom: "date_diff" },
+];
+const JSON_LOGIC_OPERATOR_SNIPPETS: Record<string, string> = {
+  if: '{\n  "if": [\n    {"var": "condition"},\n    "then_value",\n    "else_value"\n  ]\n}',
+  and: '{\n  "and": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  or: '{\n  "or": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "!": '{\n  "!": [\n    {"var": "value"}\n  ]\n}',
+  "==": '{\n  "==": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "!=": '{\n  "!=": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "<": '{\n  "<": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "<=": '{\n  "<=": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  ">": '{\n  ">": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  ">=": '{\n  ">=": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "+": '{\n  "+": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "-": '{\n  "-": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "*": '{\n  "*": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "/": '{\n  "/": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "%": '{\n  "%": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+};
+const RESERVED_DERIVED_KEY_NAMES = new Set([
+  ...JSON_LOGIC_OPERATOR_GROUPS.flatMap((group) => group.operators),
+  ...FORMULA_HELPERS.map((helper) => helper.name),
+]);
+
+type ReferenceValueKind = "any" | "number" | "datetime" | "text" | "boolean" | "range" | "unknown";
+type PendingHelperInsertState = {
+  helperName: string;
+  selectedReferences: string[];
+};
+type FormulaResultTypeHint = "number" | "text" | "boolean" | "unknown";
+
+const BUILTIN_REFERENCE_KIND_HINTS: Record<EntityType, Record<string, ReferenceValueKind>> = {
+  vendor: {
+    id: "number",
+    name: "text",
+    registered: "datetime",
+    comment: "text",
+  },
+  filament: {
+    id: "number",
+    name: "text",
+    material: "text",
+    price: "number",
+    density: "number",
+    weight: "number",
+    color_hex: "text",
+    comment: "text",
+  },
+  spool: {
+    id: "number",
+    weight: "number",
+    remaining_weight: "number",
+    used_weight: "number",
+    price: "number",
+    lot_nr: "text",
+    comment: "text",
+    created_at: "datetime",
+  },
+};
+
+function resolveColorLuminance(color: string): number | null {
+  const normalized = color.trim().toLowerCase();
+
+  const hexMatch = normalized.match(/^#([a-f0-9]{3,4}|[a-f0-9]{6}|[a-f0-9]{8})$/);
+  if (hexMatch) {
+    const hex = hexMatch[1];
+    const value =
+      hex.length === 3 || hex.length === 4
+        ? `${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}`
+        : hex.slice(0, 6);
+    const r = parseInt(value.slice(0, 2), 16);
+    const g = parseInt(value.slice(2, 4), 16);
+    const b = parseInt(value.slice(4, 6), 16);
+    return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+  }
+
+  const rgbMatch = normalized.match(/^rgba?\(([^)]+)\)$/);
+  if (!rgbMatch) {
+    return null;
+  }
+  const channels = rgbMatch[1]
+    .split(",")
+    .map((part) => part.trim())
+    .slice(0, 3);
+  if (channels.length !== 3) {
+    return null;
+  }
+
+  const toByte = (channel: string): number | null => {
+    if (channel.endsWith("%")) {
+      const percent = Number(channel.slice(0, -1));
+      if (Number.isNaN(percent)) {
+        return null;
+      }
+      return Math.round((Math.max(0, Math.min(100, percent)) / 100) * 255);
+    }
+    const value = Number(channel);
+    if (Number.isNaN(value)) {
+      return null;
+    }
+    return Math.max(0, Math.min(255, value));
+  };
+
+  const r = toByte(channels[0]);
+  const g = toByte(channels[1]);
+  const b = toByte(channels[2]);
+  if (r == null || g == null || b == null) {
+    return null;
+  }
+  return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+}
+
+function formatPreviewValue(value: string | number | boolean | null): string {
+  if (value === null) {
+    return "null";
+  }
+  return `${value}`;
+}
+
+function parseSampleValues(raw: string | undefined): Record<string, unknown> {
+  if (!raw || raw.trim() === "") {
+    return {};
+  }
+
+  const parsed = JSON.parse(raw);
+  if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+    throw new Error("Sample values must be a JSON object.");
+  }
+
+  return parsed as Record<string, unknown>;
+}
+
+function parseExpressionJson(raw: string | undefined): Record<string, unknown> | undefined {
+  if (!raw || raw.trim() === "") {
+    return undefined;
+  }
+
+  const parsed = JSON.parse(raw);
+  if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+    throw new Error("Expression JSON must be a JSON object.");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function mergeTypeHints(typeHints: FormulaResultTypeHint[]): FormulaResultTypeHint {
+  const knownHints = typeHints.filter((typeHint) => typeHint !== "unknown");
+  if (knownHints.length === 0) {
+    return "unknown";
+  }
+  return knownHints.every((typeHint) => typeHint === knownHints[0]) ? knownHints[0] : "unknown";
+}
+
+function inferExpressionJsonType(node: unknown): FormulaResultTypeHint {
+  if (typeof node === "number") {
+    return "number";
+  }
+  if (typeof node === "string") {
+    return "text";
+  }
+  if (typeof node === "boolean") {
+    return "boolean";
+  }
+  if (node === null || Array.isArray(node) || typeof node !== "object") {
+    return "unknown";
+  }
+
+  const entries = Object.entries(node as Record<string, unknown>);
+  if (entries.length !== 1) {
+    return "unknown";
+  }
+
+  const [operator, rawArgs] = entries[0];
+  const args = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+
+  if (operator === "var") {
+    return "unknown";
+  }
+
+  if (operator === "if") {
+    const branchHints: FormulaResultTypeHint[] = [];
+    for (let index = 1; index < args.length; index += 2) {
+      branchHints.push(inferExpressionJsonType(args[index]));
+    }
+    if (args.length % 2 === 0 && args.length > 0) {
+      branchHints.push(inferExpressionJsonType(args[args.length - 1]));
+    }
+    return mergeTypeHints(branchHints);
+  }
+
+  if (operator === "coalesce") {
+    return mergeTypeHints(args.map((arg) => inferExpressionJsonType(arg)));
+  }
+
+  if (["==", "!=", "<", "<=", ">", ">=", "!", "and", "or"].includes(operator)) {
+    return "boolean";
+  }
+
+  if (
+    [
+      "+",
+      "-",
+      "*",
+      "/",
+      "%",
+      "abs",
+      "min",
+      "max",
+      "round",
+      "year",
+      "month",
+      "day",
+      "hour",
+      "minute",
+      "second",
+      "timestamp",
+      "days_between",
+      "hours_between",
+      "hue_from_hex",
+      "length",
+    ].includes(operator)
+  ) {
+    return "number";
+  }
+
+  if (["date_only", "time_only", "today", "cat", "concat", "replace", "trim", "upper", "lower", "left", "right"].includes(operator)) {
+    return "text";
+  }
+
+  return "unknown";
+}
+
+function toDerivedFieldType(typeHint: FormulaResultTypeHint): DerivedFieldType | null {
+  if (typeHint === "number") {
+    return DerivedFieldType.number;
+  }
+  if (typeHint === "text") {
+    return DerivedFieldType.text;
+  }
+  return null;
+}
+
+export function FormulaFieldsSettings() {
+  const { entityType } = useParams<{ entityType: EntityType }>();
+  const t = useTranslate();
+  const { token } = theme.useToken();
+  const screens = Grid.useBreakpoint();
+  const [messageApi, contextHolder] = message.useMessage();
+  const [derivedModalOpen, setDerivedModalOpen] = useState(false);
+  const [editingDerivedKey, setEditingDerivedKey] = useState<string | null>(null);
+  const [previewText, setPreviewText] = useState<string | null>(null);
+  const [previewReferences, setPreviewReferences] = useState<string[]>([]);
+  const [pendingJsonHelperInsert, setPendingJsonHelperInsert] = useState<PendingHelperInsertState | null>(null);
+  const [resultTypeMismatchHint, setResultTypeMismatchHint] = useState<DerivedFieldType | null>(null);
+  const [operatorPanelCollapsed, setOperatorPanelCollapsed] = useState(false);
+  const [hoveredTokenId, setHoveredTokenId] = useState<string | null>(null);
+  const [derivedForm] = Form.useForm();
+  const expressionJsonEditorRef = useRef<EditorView | null>(null);
+  const expressionJsonSelectionRef = useRef<{ from: number; to: number }>({ from: 0, to: 0 });
+
+  const selectedEntityType = entityType as EntityType;
+  const niceName = t(`${selectedEntityType}.${selectedEntityType}`);
+  const sectionBodyStyle = { marginTop: 0, fontSize: token.fontSize, lineHeight: 1.7 };
+  const tokenPanelStyle = useMemo(
+    () => ({
+      border: `1px solid ${token.colorBorderSecondary}`,
+      borderRadius: token.borderRadiusLG,
+      padding: 10,
+      background: token.colorBgContainer,
+    }),
+    [token.colorBgContainer, token.colorBorderSecondary, token.borderRadiusLG],
+  );
+  const tokenCategoryStyle = useMemo(
+    () => ({
+      borderRadius: token.borderRadius,
+      border: `1px solid ${token.colorBorderSecondary}`,
+      background: token.colorFillQuaternary,
+      padding: "8px 10px",
+      minHeight: 68,
+    }),
+    [token.borderRadius, token.colorBorderSecondary, token.colorFillQuaternary],
+  );
+  const tokenListStyle = useMemo<CSSProperties>(
+    () => ({
+      display: "flex",
+      flexWrap: "wrap",
+      gap: 6,
+      marginTop: 6,
+      justifyContent: "center",
+    }),
+    [],
+  );
+  const compactHelperCategoryStyle = useMemo<CSSProperties>(
+    () => ({
+      padding: "6px",
+      minHeight: 52,
+    }),
+    [],
+  );
+  const compactHelperTokenListStyle = useMemo<CSSProperties>(
+    () => ({
+      ...tokenListStyle,
+      justifyContent: "center",
+      marginTop: 4,
+      gap: 4,
+    }),
+    [tokenListStyle],
+  );
+  const referenceGridStyle = useMemo(
+    () => ({
+      display: "grid",
+      // Keep references dense while predictable: 4 columns on desktop, 3/2 on medium widths, 1 on mobile.
+      gridTemplateColumns: screens.lg || screens.xl || screens.xxl
+        ? "repeat(4, minmax(0, 1fr))"
+        : screens.md
+          ? "repeat(3, minmax(0, 1fr))"
+          : screens.sm
+            ? "repeat(2, minmax(0, 1fr))"
+            : "repeat(1, minmax(0, 1fr))",
+      gap: 6,
+    }),
+    [screens.lg, screens.md, screens.sm, screens.xl, screens.xxl],
+  );
+  const isDesktopLayout = Boolean(screens.lg || screens.xl || screens.xxl);
+  const isDesktopOperatorPanel = isDesktopLayout;
+  const showInlineOperatorPanel = Boolean(isDesktopOperatorPanel && !operatorPanelCollapsed);
+  const codeMirrorTheme = useMemo(() => {
+    const bgLuminance = resolveColorLuminance(token.colorBgContainer);
+    const textLuminance = resolveColorLuminance(token.colorText);
+    const isDark = bgLuminance != null ? bgLuminance < 0.5 : (textLuminance ?? 0) > 0.6;
+    // Use Ant warning background tokens so selection follows the theme palette,
+    // but stays muted enough for multiline editing in dark mode.
+    const selectionColor = isDark ? token.colorWarningBg : token.colorWarningBgHover;
+    const selectionMatchColor = isDark ? "rgba(250, 173, 20, 0.24)" : "rgba(250, 173, 20, 0.18)";
+    const activeLineColor = isDark ? "rgba(250, 173, 20, 0.02)" : "rgba(22, 119, 255, 0.04)";
+    const activeLineGutterColor = isDark ? "rgba(250, 173, 20, 0.04)" : "rgba(22, 119, 255, 0.06)";
+    // Force editor foreground/background directly from design tokens so formula JSON remains
+    // readable in both light and dark themes regardless of global CSS inheritance.
+    return EditorView.theme(
+      {
+        "&": {
+          backgroundColor: token.colorBgContainer,
+          color: token.colorText,
+          borderRadius: token.borderRadius,
+          border: `1px solid ${token.colorBorder}`,
+        },
+        "&.cm-editor": {
+          backgroundColor: token.colorBgContainer,
+          color: token.colorText,
+        },
+        "& .cm-scroller": {
+          backgroundColor: token.colorBgContainer,
+          color: token.colorText,
+        },
+        "&.cm-focused": {
+          outline: `1px solid ${token.colorPrimaryBorderHover}`,
+        },
+        ".cm-scroller": {
+          fontFamily: token.fontFamilyCode || "monospace",
+        },
+        ".cm-content, .cm-line": {
+          color: token.colorText,
+          caretColor: token.colorText,
+        },
+        ".cm-cursor, .cm-dropCursor": {
+          borderLeftColor: token.colorText,
+        },
+        // Keep bracket feedback enabled (standard editor behavior) but align it to amber theme.
+        ".cm-matchingBracket": {
+          backgroundColor: `${selectionMatchColor} !important`,
+          color: token.colorText,
+          outline: `1px solid ${token.colorWarningBorder}`,
+          borderRadius: 2,
+        },
+        ".cm-nonmatchingBracket": {
+          backgroundColor: "transparent !important",
+          color: token.colorError,
+          outline: `1px solid ${token.colorErrorBorder}`,
+          borderRadius: 2,
+        },
+        // Keep selection/search matches enabled (standard behavior), but use the same amber family.
+        ".cm-content .cm-selectionMatch, .cm-content .cm-searchMatch, .cm-content .cm-searchMatch-selected": {
+          backgroundColor: `${selectionMatchColor} !important`,
+          outline: `1px solid ${token.colorWarningBorder}`,
+          border: "none !important",
+          borderRadius: 2,
+          boxShadow: "none !important",
+        },
+        ".cm-gutters": {
+          backgroundColor: token.colorBgElevated,
+          color: token.colorTextTertiary,
+          borderRight: `1px solid ${token.colorBorderSecondary}`,
+        },
+        ".cm-activeLine": {
+          backgroundColor: activeLineColor,
+        },
+        ".cm-activeLineGutter": {
+          backgroundColor: activeLineGutterColor,
+        },
+        ".cm-selectionLayer": {
+          mixBlendMode: "normal",
+        },
+        // Force one consistent drawn selection color for both focused and blurred states.
+        ".cm-selectionBackground, .cm-selectionLayer .cm-selectionBackground, &.cm-focused .cm-selectionBackground, &.cm-focused .cm-selectionLayer .cm-selectionBackground": {
+          backgroundColor: `${selectionColor} !important`,
+          borderRadius: 2,
+        },
+        // Keep native browser selection transparent so it doesn't override with platform colors.
+        ".cm-content ::selection, .cm-line ::selection, .cm-line > span::selection, .cm-content *::selection": {
+          backgroundColor: "transparent !important",
+        },
+      },
+      { dark: isDark },
+    );
+  }, [
+    token.borderRadius,
+    token.colorBgContainer,
+    token.colorBgElevated,
+    token.colorBorder,
+    token.colorBorderSecondary,
+    token.colorError,
+    token.colorErrorBorder,
+    token.colorPrimaryBorderHover,
+    token.colorText,
+    token.colorTextTertiary,
+    token.colorWarningBorder,
+    token.colorWarningBg,
+    token.colorWarningBgHover,
+    token.fontFamilyCode,
+  ]);
+  useEffect(() => {
+    if (!isDesktopOperatorPanel) {
+      setOperatorPanelCollapsed(true);
+      return;
+    }
+    setOperatorPanelCollapsed(false);
+  }, [isDesktopOperatorPanel, derivedModalOpen]);
+
+  const derivedFields = useGetDerivedFields(selectedEntityType);
+  const configuredFields = useGetFields(selectedEntityType);
+  const setDerivedField = useSetDerivedField(selectedEntityType);
+  const deleteDerivedField = useDeleteDerivedField(selectedEntityType);
+  const previewDerivedField = usePreviewDerivedField(selectedEntityType);
+  const expressionJsonValue = Form.useWatch("expression_json", derivedForm) as string | undefined;
+  const derivedKeyValue = ((Form.useWatch("key", derivedForm) as string | undefined) || "").trim();
+  // Show the concrete API/template path for the currently typed key to remove
+  // ambiguity between formula operator names and field output identifiers.
+  const derivedKeyPath = useMemo(
+    () => (derivedKeyValue ? `derived.${derivedKeyValue}` : "derived.<key>"),
+    [derivedKeyValue],
+  );
+  const keyLooksLikeReservedToken = useMemo(
+    () => RESERVED_DERIVED_KEY_NAMES.has(derivedKeyValue),
+    [derivedKeyValue],
+  );
+
+  const sampleValuesPlaceholder = SAMPLE_VALUE_PLACEHOLDERS[selectedEntityType];
+
+  const labeledField = (labelKey: string, tooltipKey: string) => (
+    <Space size={4}>
+      <span>{t(labelKey)}</span>
+      <Tooltip title={t(tooltipKey)}>
+        <QuestionCircleOutlined />
+      </Tooltip>
+    </Space>
+  );
+
+  const referenceOptions = useMemo(() => {
+    const extraReferences = (configuredFields.data || []).map((field) => `extra.${field.key}`);
+    // Suggest both built-in fields and configured extra fields so users can compose formulas
+    // without memorizing the exact reference syntax for each entity.
+    return [...new Set([...BUILTIN_REFERENCE_SUGGESTIONS[selectedEntityType], ...extraReferences])];
+  }, [configuredFields.data, selectedEntityType]);
+  const compactReferenceOptions = useMemo(
+    () =>
+      referenceOptions.map((reference) => ({
+        value: reference,
+        label: `{${reference}}`,
+      })),
+    [referenceOptions],
+  );
+  const helperByName = useMemo(
+    () => Object.fromEntries(FORMULA_HELPERS.map((helper) => [helper.name, helper] as const)),
+    [],
+  );
+  const operatorGroups = useMemo(
+    () =>
+      JSON_LOGIC_OPERATOR_GROUPS.map((group) => ({
+        ...group,
+        label: t(`settings.complex_fields.formula.token_categories.${group.key}`),
+      })),
+    [t],
+  );
+  const helperGroups = useMemo(
+    () =>
+      FORMULA_HELPER_GROUPS.map((group) => ({
+        ...group,
+        label: t(`settings.complex_fields.formula.token_categories.${group.key}`),
+      })),
+    [t],
+  );
+  const helperGroupByKey = useMemo(
+    () => Object.fromEntries(helperGroups.map((group) => [group.key, group])),
+    [helperGroups],
+  );
+  const referenceKindByName = useMemo(() => {
+    const map: Record<string, ReferenceValueKind> = {
+      ...BUILTIN_REFERENCE_KIND_HINTS[selectedEntityType],
+    };
+
+    (configuredFields.data || []).forEach((field) => {
+      const fieldKind: ReferenceValueKind = (() => {
+        switch (field.field_type) {
+          case FieldType.integer:
+          case FieldType.float:
+            return "number";
+          case FieldType.datetime:
+            return "datetime";
+          case FieldType.boolean:
+            return "boolean";
+          case FieldType.integer_range:
+          case FieldType.float_range:
+            return "range";
+          case FieldType.text:
+          case FieldType.choice:
+            return "text";
+          default:
+            return "unknown";
+        }
+      })();
+      map[`extra.${field.key}`] = fieldKind;
+    });
+
+    return map;
+  }, [configuredFields.data, selectedEntityType]);
+  const getHelperReferenceCount = (helper: FormulaHelperDefinition): number => {
+    if (helper.insert_mode === "none") {
+      return 0;
+    }
+    return helper.reference_count ?? 1;
+  };
+  const helperAllowsReferenceKind = (helper: FormulaHelperDefinition, referenceKind: ReferenceValueKind): boolean => {
+    const requiredKind = helper.reference_kind ?? "any";
+    if (requiredKind === "any") {
+      return true;
+    }
+    return referenceKind === requiredKind;
+  };
+  const pendingHelperDefinition = useMemo(() => {
+    if (!pendingJsonHelperInsert) {
+      return null;
+    }
+    return helperByName[pendingJsonHelperInsert.helperName] || null;
+  }, [helperByName, pendingJsonHelperInsert]);
+  const getHelperDisabledReason = (helper: FormulaHelperDefinition): string | null => {
+    if (helper.insert_mode === "none") {
+      return null;
+    }
+
+    const requiredRefCount = getHelperReferenceCount(helper);
+    const compatibleReferences = referenceOptions.filter((reference) =>
+      helperAllowsReferenceKind(helper, referenceKindByName[reference] || "unknown"),
+    );
+    if (compatibleReferences.length < requiredRefCount) {
+      return t("settings.complex_fields.formula.json_builder.helper_unavailable_reason", { helper: helper.name });
+    }
+
+    // When the user already picked reference #1 for a pending helper, temporarily disable helper
+    // tokens that can't accept that selected reference kind. Clearing/completing pending insert
+    // resets all helper tokens back to normal.
+    if (pendingJsonHelperInsert?.selectedReferences.length) {
+      const selectedKind = referenceKindByName[pendingJsonHelperInsert.selectedReferences[0]] || "unknown";
+      if (!helperAllowsReferenceKind(helper, selectedKind)) {
+        return t("settings.complex_fields.formula.json_builder.helper_incompatible_reason", { helper: helper.name });
+      }
+    }
+
+    return null;
+  };
+  const isReferenceCompatibleWithPendingHelper = (reference: string): boolean => {
+    if (!pendingHelperDefinition) {
+      return true;
+    }
+    const referenceKind = referenceKindByName[reference] || "unknown";
+    return helperAllowsReferenceKind(pendingHelperDefinition, referenceKind);
+  };
+  const buildHelperPlaceholderArguments = (helper: FormulaHelperDefinition): Array<{ var: string }> => {
+    const referenceCount = getHelperReferenceCount(helper);
+    if (referenceCount <= 0) {
+      return [];
+    }
+    if (referenceCount === 1) {
+      return [{ var: "value" }];
+    }
+    if (referenceCount === 2) {
+      return [{ var: "start" }, { var: "end" }];
+    }
+    return Array.from({ length: referenceCount }, (_, index) => ({ var: `arg_${index + 1}` }));
+  };
+  const helperTokenGridStyle = useMemo<CSSProperties>(
+    () => ({
+      display: "grid",
+      // Desktop uses a dedicated stacked helper layout; this fallback handles narrower widths.
+      gridTemplateColumns: screens.md || screens.sm ? "repeat(2, minmax(0, 1fr))" : "repeat(1, minmax(0, 1fr))",
+      gap: 8,
+      alignItems: "start",
+    }),
+    [screens.md, screens.sm],
+  );
+  const renderTokenCategory = (
+    key: string,
+    label: string,
+    tokens: ReactNode,
+    style?: CSSProperties,
+    tokenContainerStyle?: CSSProperties,
+  ) => (
+    <div key={key} style={{ ...tokenCategoryStyle, ...style }}>
+      <Typography.Text type="secondary">
+        <strong>{label}</strong>
+      </Typography.Text>
+      <div style={tokenContainerStyle ?? tokenListStyle}>{tokens}</div>
+    </div>
+  );
+  const renderOperatorTokenGroups = (interactive: boolean) => (
+    <div style={{ display: "grid", gap: 6 }}>
+      {operatorGroups.map((group) => {
+        const compactTitle =
+          group.key === "logical"
+            ? (
+              <>
+                {t("settings.complex_fields.formula.json_builder.operator_compact.logical_top")}
+                <br />
+                {t("settings.complex_fields.formula.json_builder.operator_compact.logical_bottom")}
+              </>
+            )
+            : group.key === "comparison"
+              ? t("settings.complex_fields.formula.json_builder.operator_compact.comparison")
+              : t("settings.complex_fields.formula.json_builder.operator_compact.math");
+        const operatorGridColumns = group.key === "logical" ? "repeat(2, max-content)" : "repeat(3, max-content)";
+        const labelColumnWidth = group.key === "logical" ? 90 : 78;
+        return (
+          <div
+            key={group.key}
+            style={{
+              ...tokenCategoryStyle,
+              minHeight: 54,
+              padding: "6px 8px",
+              display: "grid",
+              gridTemplateColumns: `1fr ${labelColumnWidth}px`,
+              alignItems: "center",
+              columnGap: 6,
+            }}
+          >
+            <div
+              style={{
+                display: "grid",
+                gridTemplateColumns: operatorGridColumns,
+                gap: 3,
+                justifyItems: "center",
+                justifyContent: "start",
+              }}
+            >
+              {group.operators.map((operator) => (
+                (() => {
+                  const tokenId = `operator-${group.key}-${operator}`;
+                  const isHovered = hoveredTokenId === tokenId;
+                  return (
+                    <Typography.Text
+                      key={tokenId}
+                      code
+                      style={{
+                        cursor: interactive ? "pointer" : "default",
+                        minWidth: 20,
+                        textAlign: "center",
+                        whiteSpace: "nowrap",
+                        wordBreak: "normal",
+                        overflowWrap: "normal",
+                        color: interactive && isHovered ? token.colorWarningText : undefined,
+                        background: interactive && isHovered ? token.colorWarningBg : undefined,
+                        borderColor: interactive && isHovered ? token.colorWarningBorder : undefined,
+                        transition: "all 120ms ease-out",
+                      }}
+                      onMouseEnter={interactive ? () => setHoveredTokenId(tokenId) : undefined}
+                      onMouseLeave={interactive ? () => setHoveredTokenId((current) => (current === tokenId ? null : current)) : undefined}
+                      onClick={interactive ? () => insertExpressionJsonOperator(operator) : undefined}
+                    >
+                      {operator}
+                    </Typography.Text>
+                  );
+                })()
+              ))}
+            </div>
+            <Typography.Text type="secondary">
+              <strong style={{ lineHeight: 1.1, fontSize: "0.92em", whiteSpace: "nowrap", textAlign: "right", display: "block" }}>
+                {compactTitle}
+              </strong>
+            </Typography.Text>
+          </div>
+        );
+      })}
+    </div>
+  );
+  const renderHelperTokenCategory = (
+    groupKey: string,
+    interactive: boolean,
+    compact = false,
+  ) => {
+    const group = helperGroupByKey[groupKey];
+    if (!group || group.helpers.length === 0) {
+      return null;
+    }
+    return renderTokenCategory(
+      group.key,
+      group.label,
+      group.helpers.map((helper) => {
+        const disabledReason = interactive ? getHelperDisabledReason(helper) : null;
+        const tokenId = `helper-${helper.name}`;
+        const isHovered = hoveredTokenId === tokenId;
+        const helperToken = (
+          <Typography.Text
+            code
+            style={{
+              cursor: interactive ? (disabledReason ? "not-allowed" : "pointer") : "default",
+              opacity: disabledReason ? 0.45 : 1,
+              whiteSpace: "nowrap",
+              wordBreak: "normal",
+              overflowWrap: "normal",
+              flexShrink: 0,
+              color: interactive && !disabledReason && isHovered ? token.colorWarningText : undefined,
+              background: interactive && !disabledReason && isHovered ? token.colorWarningBg : undefined,
+              borderColor: interactive && !disabledReason && isHovered ? token.colorWarningBorder : undefined,
+              transition: "all 120ms ease-out",
+            }}
+            onMouseEnter={interactive && !disabledReason ? () => setHoveredTokenId(tokenId) : undefined}
+            onMouseLeave={interactive && !disabledReason ? () => setHoveredTokenId((current) => (current === tokenId ? null : current)) : undefined}
+            onClick={interactive && !disabledReason ? () => insertExpressionJsonHelper(helper) : undefined}
+          >
+            {helper.name}
+          </Typography.Text>
+        );
+        return (
+          <Tooltip key={`helper-${helper.name}`} title={interactive ? disabledReason || undefined : undefined}>
+            <span style={{ display: "inline-flex" }}>{helperToken}</span>
+          </Tooltip>
+        );
+      }),
+      compact ? compactHelperCategoryStyle : undefined,
+      compact ? compactHelperTokenListStyle : undefined,
+    );
+  };
+  const renderHelperTokenGroups = (interactive: boolean) => {
+    if (isDesktopLayout) {
+      return (
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: "repeat(4, minmax(0, 1fr))",
+            gap: 8,
+            alignItems: "start",
+          }}
+        >
+          {HELPER_DESKTOP_COLUMN_LAYOUT.map((column) => (
+            <div key={`helper-column-${column.top}`} style={{ display: "grid", gap: 8, alignContent: "start" }}>
+              {renderHelperTokenCategory(column.top, interactive)}
+              {column.bottom ? renderHelperTokenCategory(column.bottom, interactive, true) : null}
+            </div>
+          ))}
+        </div>
+      );
+    }
+    return (
+      <div style={helperTokenGridStyle}>
+        {helperGroups.map((group) => renderHelperTokenCategory(group.key, interactive))}
+      </div>
+    );
+  };
+
+  const missingCustomReferencesByDerivedField = useMemo(() => {
+    const availableCustomFieldKeys = new Set((configuredFields.data || []).map((field) => field.key));
+    const missingMap: Record<string, string[]> = {};
+
+    (derivedFields.data || []).forEach((derivedField) => {
+      const missingReferences = getExtraFieldReferences(derivedField.expression_json || undefined).filter(
+        (reference) => !availableCustomFieldKeys.has(reference),
+      );
+      if (missingReferences.length > 0) {
+        missingMap[derivedField.key] = missingReferences;
+      }
+    });
+
+    return missingMap;
+  }, [configuredFields.data, derivedFields.data]);
+
+  const hasBrokenFormulaDependencies = useMemo(
+    () => Object.keys(missingCustomReferencesByDerivedField).length > 0,
+    [missingCustomReferencesByDerivedField],
+  );
+
+  const openCreateDerived = () => {
+    setEditingDerivedKey(null);
+    setPreviewText(null);
+    setPreviewReferences([]);
+    setResultTypeMismatchHint(null);
+    derivedForm.resetFields();
+    derivedForm.setFieldsValue({
+      key: "",
+      name: "",
+      description: "",
+      result_type: DerivedFieldType.number,
+      surfaces: [ComplexFieldSurface.show],
+      allow_list_column_toggle: false,
+      include_in_api: false,
+      expression_json: "",
+      sample_values: "{}",
+    });
+    setDerivedModalOpen(true);
+  };
+
+  const openEditDerived = (record: DerivedField) => {
+    setEditingDerivedKey(record.key);
+    setPreviewText(null);
+    setPreviewReferences([]);
+    setResultTypeMismatchHint(null);
+    derivedForm.setFieldsValue({
+      key: record.key,
+      name: record.name,
+      description: record.description || "",
+      result_type: record.result_type,
+      surfaces: record.surfaces,
+      allow_list_column_toggle: record.allow_list_column_toggle,
+      include_in_api: record.include_in_api ?? false,
+      expression_json: record.expression_json ? JSON.stringify(record.expression_json, null, 2) : "",
+      sample_values: "{}",
+    });
+    setDerivedModalOpen(true);
+  };
+
+  const closeDerivedModal = () => {
+    setDerivedModalOpen(false);
+    setEditingDerivedKey(null);
+    setPreviewText(null);
+    setPreviewReferences([]);
+    setResultTypeMismatchHint(null);
+    setPendingJsonHelperInsert(null);
+    expressionJsonSelectionRef.current = { from: 0, to: 0 };
+    derivedForm.resetFields();
+  };
+
+  const insertExpressionJsonSnippet = (snippet: string) => {
+    const currentValue = (derivedForm.getFieldValue("expression_json") as string | undefined) || "";
+    const hasEditor = expressionJsonEditorRef.current !== null;
+    if (!hasEditor) {
+      const prefix = currentValue.trim() === "" ? "" : "\n";
+      derivedForm.setFieldValue("expression_json", `${currentValue}${prefix}${snippet}`);
+      return;
+    }
+
+    const start = expressionJsonSelectionRef.current.from;
+    const end = expressionJsonSelectionRef.current.to;
+    const nextValue = `${currentValue.slice(0, start)}${snippet}${currentValue.slice(end)}`;
+    const nextCursor = start + snippet.length;
+    derivedForm.setFieldValue("expression_json", nextValue);
+    expressionJsonSelectionRef.current = { from: nextCursor, to: nextCursor };
+
+    requestAnimationFrame(() => {
+      const editor = expressionJsonEditorRef.current;
+      if (!editor) {
+        return;
+      }
+      editor.focus();
+      editor.dispatch({
+        selection: { anchor: nextCursor, head: nextCursor },
+        scrollIntoView: true,
+      });
+    });
+  };
+
+  const insertExpressionJsonReference = (reference: string) => {
+    if (!pendingHelperDefinition) {
+      insertExpressionJsonSnippet(JSON.stringify({ var: reference }, null, 2));
+      return;
+    }
+
+    if (!isReferenceCompatibleWithPendingHelper(reference)) {
+      messageApi.warning(
+        t("settings.complex_fields.formula.json_builder.reference_incompatible_reason", {
+          helper: pendingHelperDefinition.name,
+        }),
+      );
+      return;
+    }
+
+    const pendingState = pendingJsonHelperInsert;
+    if (!pendingState) {
+      return;
+    }
+    const requiredReferenceCount = getHelperReferenceCount(pendingHelperDefinition);
+    const selectedReferences = [...pendingState.selectedReferences, reference];
+    if (selectedReferences.length < requiredReferenceCount) {
+      setPendingJsonHelperInsert({
+        helperName: pendingHelperDefinition.name,
+        selectedReferences,
+      });
+      return;
+    }
+
+    const snippet = {
+      [pendingHelperDefinition.name]: selectedReferences
+        .slice(0, requiredReferenceCount)
+        .map((selectedReference) => ({ var: selectedReference })),
+    };
+    // Insert ready-to-parse JSON Logic objects so users can build expressions without memorizing
+    // raw AST syntax.
+    insertExpressionJsonSnippet(JSON.stringify(snippet, null, 2));
+    setPendingJsonHelperInsert(null);
+  };
+
+  const insertExpressionJsonHelper = (helper: FormulaHelperDefinition) => {
+    if (helper.insert_mode === "none") {
+      insertExpressionJsonSnippet(JSON.stringify({ [helper.name]: [] }, null, 2));
+      setPendingJsonHelperInsert(null);
+      return;
+    }
+    const disabledReason = getHelperDisabledReason(helper);
+    if (disabledReason) {
+      messageApi.warning(disabledReason);
+      return;
+    }
+    // Keep helper insertion staged until required reference tokens are selected, so helpers with
+    // multiple reference operands (for example days_between/hours_between) can be assembled safely.
+    setPendingJsonHelperInsert({ helperName: helper.name, selectedReferences: [] });
+    messageApi.info(
+      t("settings.complex_fields.formula.json_builder.pending_helper", {
+        helper: helper.name,
+        selected: 0,
+        total: getHelperReferenceCount(helper),
+      }),
+    );
+  };
+
+  const insertPendingHelperWithoutReferences = () => {
+    if (!pendingHelperDefinition) {
+      return;
+    }
+    const placeholderSnippet = {
+      [pendingHelperDefinition.name]: buildHelperPlaceholderArguments(pendingHelperDefinition),
+    };
+    insertExpressionJsonSnippet(JSON.stringify(placeholderSnippet, null, 2));
+    setPendingJsonHelperInsert(null);
+  };
+  const cancelPendingHelperInsert = () => {
+    setPendingJsonHelperInsert(null);
+  };
+
+  const insertExpressionJsonOperator = (operator: string) => {
+    const snippet = JSON_LOGIC_OPERATOR_SNIPPETS[operator];
+    if (!snippet) {
+      return;
+    }
+    insertExpressionJsonSnippet(snippet);
+    setPendingJsonHelperInsert(null);
+  };
+
+  const formatExpressionJson = async () => {
+    try {
+      const currentValue = (derivedForm.getFieldValue("expression_json") as string | undefined) || "";
+      const parsed = parseExpressionJson(currentValue);
+      if (!parsed) {
+        setResultTypeMismatchHint(null);
+        return;
+      }
+      const selectedResultType = derivedForm.getFieldValue("result_type") as DerivedFieldType | undefined;
+      const inferredType = toDerivedFieldType(inferExpressionJsonType(parsed));
+      if (selectedResultType && inferredType && inferredType !== selectedResultType) {
+        setResultTypeMismatchHint(inferredType);
+      } else {
+        setResultTypeMismatchHint(null);
+      }
+      derivedForm.setFieldValue("expression_json", JSON.stringify(parsed, null, 2));
+      messageApi.success(t("settings.complex_fields.formula.json_builder.formatted"));
+    } catch (errInfo) {
+      if (errInfo instanceof Error) {
+        messageApi.error(errInfo.message);
+      }
+    }
+  };
+
+  const saveDerived = async () => {
+    try {
+      const values = await derivedForm.validateFields();
+      const key = editingDerivedKey || values.key;
+      const expressionJson = parseExpressionJson(values.expression_json);
+      if (!expressionJson) {
+        throw new Error(t("settings.complex_fields.formula.expression_json_required"));
+      }
+      if (expressionJson) {
+        const inferredType = toDerivedFieldType(inferExpressionJsonType(expressionJson));
+        if (inferredType && inferredType !== values.result_type) {
+          setResultTypeMismatchHint(inferredType);
+        } else {
+          setResultTypeMismatchHint(null);
+        }
+      } else {
+        setResultTypeMismatchHint(null);
+      }
+
+      await setDerivedField.mutateAsync({
+        key,
+        params: {
+          name: values.name,
+          description: values.description || undefined,
+          result_type: values.result_type,
+          expression_json: expressionJson,
+          surfaces: values.surfaces,
+          allow_list_column_toggle: values.allow_list_column_toggle,
+          include_in_api: values.include_in_api ?? false,
+        },
+      });
+
+      messageApi.success(
+        t(editingDerivedKey ? "settings.complex_fields.formula.messages.updated" : "settings.complex_fields.formula.messages.created", {
+          name: values.name,
+        }),
+      );
+      closeDerivedModal();
+    } catch (errInfo) {
+      if (errInfo instanceof Error) {
+        messageApi.error(errInfo.message);
+      }
+    }
+  };
+
+  const previewDerived = async () => {
+    try {
+      const values = await derivedForm.validateFields(["expression_json", "sample_values"]);
+      const sampleValues = parseSampleValues(values.sample_values);
+      const expressionJson = parseExpressionJson(values.expression_json);
+      if (!expressionJson) {
+        throw new Error(t("settings.complex_fields.formula.expression_json_required"));
+      }
+      // Preview uses sample JSON only as a sandbox for validating formulas before they are exposed
+      // on show/list/template surfaces.
+      const preview = await previewDerivedField.mutateAsync({
+        expression_json: expressionJson,
+        sample_values: sampleValues,
+      });
+
+      setPreviewText(formatPreviewValue(preview.result));
+      setPreviewReferences(preview.references);
+    } catch (errInfo) {
+      if (errInfo instanceof Error) {
+        messageApi.error(errInfo.message);
+      }
+    }
+  };
+
+  const removeDerived = async (record: DerivedField) => {
+    try {
+      await deleteDerivedField.mutateAsync(record.key);
+      messageApi.success(t("settings.complex_fields.formula.messages.deleted", { name: record.name }));
+    } catch (errInfo) {
+      if (errInfo instanceof Error) {
+        messageApi.error(errInfo.message);
+      }
+    }
+  };
+
+  const derivedColumns: ColumnType<DerivedField>[] = [
+    {
+      title: t("settings.complex_fields.formula.columns.key"),
+      dataIndex: "key",
+      key: "key",
+      width: "12%",
+    },
+    {
+      title: t("settings.complex_fields.formula.columns.name"),
+      dataIndex: "name",
+      key: "name",
+      width: "16%",
+    },
+    {
+      title: t("settings.complex_fields.formula.columns.result_type"),
+      dataIndex: "result_type",
+      key: "result_type",
+      width: "10%",
+      render: (value: DerivedFieldType) => t(`settings.complex_fields.formula.types.${value}`),
+    },
+    {
+      title: t("settings.complex_fields.formula.columns.expression"),
+      dataIndex: "expression_json",
+      key: "expression",
+      width: "30%",
+      render: (_value: Record<string, unknown> | undefined, record) => {
+        const expressionValue = record.expression_json ? JSON.stringify(record.expression_json) : "";
+        const missingReferences = missingCustomReferencesByDerivedField[record.key] || [];
+        return (
+          <Space direction="vertical" size={4}>
+            <Typography.Text code style={{ whiteSpace: "normal", wordBreak: "break-word" }}>
+              {expressionValue}
+            </Typography.Text>
+            {missingReferences.length > 0 && (
+              <Typography.Text type="danger">
+                {t("settings.complex_fields.formula.missing_references", {
+                  references: missingReferences.join(", "),
+                })}
+              </Typography.Text>
+            )}
+          </Space>
+        );
+      },
+    },
+    {
+      title: t("settings.complex_fields.formula.columns.surfaces"),
+      dataIndex: "surfaces",
+      key: "surfaces",
+      width: "16%",
+      render: (surfaces: string[]) => (
+        <Space size={[4, 4]} wrap>
+          {surfaces.map((surface) => (
+            <Tag key={surface}>{t(`settings.complex_fields.surfaces.${surface}`)}</Tag>
+          ))}
+        </Space>
+      ),
+    },
+    {
+      title: t("settings.complex_fields.formula.columns.include_in_api"),
+      dataIndex: "include_in_api",
+      key: "include_in_api",
+      width: "10%",
+      render: (value: boolean) => (value ? <Tag color="processing">API</Tag> : <Tag>{t("no")}</Tag>),
+    },
+    {
+      title: "",
+      key: "operation",
+      width: "16%",
+      render: (_: unknown, record) => (
+        <Space>
+          <Button onClick={() => openEditDerived(record)} size="small">
+            {t("buttons.edit")}
+          </Button>
+          <Popconfirm
+            title={t("settings.complex_fields.formula.delete_confirm", { name: record.name })}
+            onConfirm={() => removeDerived(record)}
+            okText={t("buttons.delete")}
+            cancelText={t("buttons.cancel")}
+          >
+            <Button danger size="small">
+              {t("buttons.delete")}
+            </Button>
+          </Popconfirm>
+        </Space>
+      ),
+    },
+  ];
+
+  const previewSummary = useMemo(() => {
+    if (previewText == null) {
+      return null;
+    }
+
+    const referencesText =
+      previewReferences.length > 0
+        ? t("settings.complex_fields.formula.preview.references_used", {
+            references: previewReferences.join(", "),
+          })
+        : t("settings.complex_fields.formula.preview.no_references");
+
+    return (
+      <Typography.Paragraph
+        style={{
+          marginBottom: 0,
+        }}
+      >
+        <strong>{t("settings.complex_fields.formula.preview.result_label")}</strong> {previewText}
+        <br />
+        {referencesText}
+      </Typography.Paragraph>
+    );
+  }, [previewReferences, previewText, t]);
+  const pendingHelperHint = useMemo(() => {
+    if (!pendingHelperDefinition || !pendingJsonHelperInsert) {
+      return null;
+    }
+    const selected = pendingJsonHelperInsert.selectedReferences.length;
+    const total = getHelperReferenceCount(pendingHelperDefinition);
+    return {
+      helper: pendingHelperDefinition.name,
+      selected,
+      total,
+    };
+  }, [pendingHelperDefinition, pendingJsonHelperInsert]);
+  return (
+    <>
+      <Divider orientation="left" plain>
+        <Space size={8}>
+          <span>
+            {t("settings.complex_fields.formula.header")}: {niceName}
+          </span>
+          <Tooltip title={t("settings.complex_fields.formula.tooltip")}>
+            <QuestionCircleOutlined />
+          </Tooltip>
+          <Link
+            style={{
+              fontSize: "0.85em",
+            }}
+            to="/help#formula-fields"
+          >
+            {t("settings.complex_fields.help_links.formula")}
+          </Link>
+        </Space>
+      </Divider>
+      <Typography.Paragraph type="secondary" style={sectionBodyStyle}>
+        {t("settings.complex_fields.formula.intro")}
+      </Typography.Paragraph>
+      <Typography.Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: -8 }}>
+        {t("settings.complex_fields.formula.evaluation_model_help")}
+      </Typography.Paragraph>
+      {hasBrokenFormulaDependencies && (
+        <Typography.Paragraph type="danger" style={{ marginTop: 0 }}>
+          {t("settings.complex_fields.formula.missing_references_intro")}
+        </Typography.Paragraph>
+      )}
+      <Typography.Paragraph type="secondary" style={{ ...sectionBodyStyle, marginBottom: 12 }}>
+        {t("settings.complex_fields.available_functions.value")}
+      </Typography.Paragraph>
+      <Table
+        columns={derivedColumns}
+        dataSource={derivedFields.data || []}
+        loading={derivedFields.isLoading}
+        pagination={false}
+        locale={{
+          emptyText: (
+            <Empty
+              description={t("settings.complex_fields.formula.empty")}
+              image={Empty.PRESENTED_IMAGE_SIMPLE}
+            />
+          ),
+        }}
+        onRow={(record) => {
+          const hasMissingReferences = (missingCustomReferencesByDerivedField[record.key] || []).length > 0;
+          if (!hasMissingReferences) {
+            return {};
+          }
+          return {
+            style: {
+              backgroundColor: token.colorErrorBg,
+            },
+          };
+        }}
+        rowKey="key"
+      />
+      <Flex justify="center">
+        <Button
+          type="primary"
+          shape="circle"
+          icon={<PlusOutlined />}
+          size="large"
+          style={{
+            margin: "1em",
+          }}
+          onClick={() => openCreateDerived()}
+        />
+      </Flex>
+
+      <Modal
+        destroyOnHidden
+        onCancel={() => closeDerivedModal()}
+        onOk={() => saveDerived()}
+        open={derivedModalOpen}
+        okText={t("buttons.save")}
+        cancelText={t("buttons.cancel")}
+        title={`${t(
+          editingDerivedKey
+            ? "settings.complex_fields.formula.modal.edit_title"
+            : "settings.complex_fields.formula.modal.create_title",
+        )}: ${niceName}`}
+        width={820}
+      >
+        <Form
+          form={derivedForm}
+          layout="vertical"
+          initialValues={{
+            result_type: DerivedFieldType.number,
+            surfaces: [ComplexFieldSurface.show],
+            allow_list_column_toggle: false,
+            include_in_api: false,
+            expression_json: "",
+            sample_values: "{}",
+          }}
+        >
+          {/* Responsive split: two columns on medium+ screens, stacked flow on narrow/mobile widths. */}
+          <Row gutter={12}>
+            <Col xs={24} md={12}>
+              <Form.Item
+                label={labeledField(
+                  "settings.complex_fields.formula.columns.key",
+                  "settings.complex_fields.formula.tooltips.key",
+                )}
+                name="key"
+                extra={(
+                  <Space direction="vertical" size={2} style={{ width: "100%" }}>
+                    <Typography.Text type="secondary">
+                      {t("settings.complex_fields.formula.key_usage_help")}: <Typography.Text code>{derivedKeyPath}</Typography.Text>
+                    </Typography.Text>
+                    {keyLooksLikeReservedToken && (
+                      <Typography.Text type="warning">
+                        <WarningOutlined style={{ marginRight: 6 }} />
+                        {t("settings.complex_fields.formula.key_reserved_hint", { key: derivedKeyValue })}
+                      </Typography.Text>
+                    )}
+                  </Space>
+                )}
+                rules={[
+                  { required: true, min: 1, max: 64, pattern: /^[a-z0-9_]+$/ },
+                  {
+                    validator: async (_, value) => {
+                      if (!editingDerivedKey && derivedFields.data?.some((field) => field.key === value)) {
+                        throw new Error(t("settings.extra_fields.non_unique_key_error"));
+                      }
+                    },
+                  },
+                ]}
+              >
+                <Input disabled={editingDerivedKey != null} />
+              </Form.Item>
+            </Col>
+            <Col xs={24} md={12}>
+              <Form.Item
+                label={labeledField(
+                  "settings.complex_fields.formula.columns.name",
+                  "settings.complex_fields.formula.tooltips.name",
+                )}
+                name="name"
+                rules={[{ required: true, min: 1, max: 128 }]}
+              >
+                <Input />
+              </Form.Item>
+            </Col>
+          </Row>
+          <Form.Item label={t("settings.complex_fields.formula.columns.description")} name="description" rules={[{ max: 512 }]}>
+            <Input.TextArea autoSize={{ minRows: 2, maxRows: 4 }} />
+          </Form.Item>
+          {/* Keep Display In aligned with Result Type on desktop while preserving form order when stacked. */}
+          <Row gutter={12}>
+            <Col xs={24} md={12}>
+              <Form.Item
+                label={(
+                  <Space size={6}>
+                    <span>{t("settings.complex_fields.formula.columns.result_type")}</span>
+                    {resultTypeMismatchHint && (
+                      <>
+                        <Tooltip
+                          title={t("settings.complex_fields.formula.result_type_mismatch_hint", {
+                            inferred: t(`settings.complex_fields.formula.types.${resultTypeMismatchHint}`),
+                          })}
+                        >
+                          <WarningOutlined style={{ color: token.colorWarning }} />
+                        </Tooltip>
+                        <Button
+                          type="link"
+                          size="small"
+                          style={{ padding: 0, height: "auto", lineHeight: 1 }}
+                          onClick={() => {
+                            derivedForm.setFieldValue("result_type", resultTypeMismatchHint);
+                            setResultTypeMismatchHint(null);
+                          }}
+                        >
+                          {t("settings.complex_fields.formula.result_type_autoset")}
+                        </Button>
+                      </>
+                    )}
+                  </Space>
+                )}
+                name="result_type"
+                rules={[{ required: true }]}
+              >
+                <Select
+                  options={[
+                    { label: t("settings.complex_fields.formula.types.number"), value: DerivedFieldType.number },
+                    { label: t("settings.complex_fields.formula.types.text"), value: DerivedFieldType.text },
+                  ]}
+                />
+              </Form.Item>
+            </Col>
+            <Col xs={24} md={12}>
+              <Form.Item
+                label={labeledField(
+                  "settings.complex_fields.formula.columns.surfaces",
+                  "settings.complex_fields.formula.tooltips.display_in",
+                )}
+                required
+              >
+                <Flex gap={12} align="center" wrap>
+                  <Form.Item name="surfaces" rules={[{ required: true, type: "array", min: 1 }]} noStyle>
+                    <Select
+                      mode="multiple"
+                      style={{ width: "100%" }}
+                      options={DERIVED_SURFACE_OPTIONS.map((surface) => ({
+                        label: t(`settings.complex_fields.surfaces.${surface}`),
+                        value: surface,
+                      }))}
+                      onChange={(selected: string[]) => {
+                        if (!selected.includes(ComplexFieldSurface.list)) {
+                          derivedForm.setFieldValue("allow_list_column_toggle", false);
+                        }
+                      }}
+                    />
+                  </Form.Item>
+                  <Form.Item shouldUpdate noStyle>
+                    {({ getFieldValue }) => {
+                      const selectedSurfaces = (getFieldValue("surfaces") as string[] | undefined) || [];
+                      const listEnabled = selectedSurfaces.includes(ComplexFieldSurface.list);
+                      if (!listEnabled) {
+                        return null;
+                      }
+
+                      return (
+                        <Space size={8}>
+                          <Form.Item name="allow_list_column_toggle" valuePropName="checked" noStyle>
+                            <Switch />
+                          </Form.Item>
+                          <Typography.Text type="secondary" style={{ whiteSpace: "nowrap" }}>
+                            {t("settings.complex_fields.formula.allow_list_column_toggle_inline", { entity: niceName })}
+                          </Typography.Text>
+                        </Space>
+                      );
+                    }}
+                  </Form.Item>
+                </Flex>
+              </Form.Item>
+            </Col>
+          </Row>
+          <Form.Item
+            style={{ marginBottom: 4 }}
+            label={
+              <Space direction="vertical" size={2} style={{ width: "100%" }}>
+                <Flex justify="space-between" align="center" gap={8} wrap={false}>
+                  <Space size={8} align="center" wrap>
+                    {labeledField(
+                      "settings.complex_fields.formula.columns.expression_json",
+                      "settings.complex_fields.formula.tooltips.expression_json",
+                    )}
+                    <Link style={{ fontSize: "0.85em" }} to="/help#formula-json-logic">
+                      {t("settings.complex_fields.help_links.formula_json")}
+                    </Link>
+                  </Space>
+                </Flex>
+                <Typography.Text type="secondary" style={{ minWidth: 0 }}>
+                  {t("settings.complex_fields.formula.expression_json_help")}
+                </Typography.Text>
+                <Typography.Text type="secondary" style={{ minWidth: 0 }}>
+                  {t("settings.complex_fields.formula.expression_json_example")}
+                </Typography.Text>
+              </Space>
+            }
+            name="expression_json"
+            trigger="onChange"
+            getValueFromEvent={(value: string) => value}
+            rules={[
+              {
+                validator: async (_, value) => {
+                  const parsed = parseExpressionJson(value);
+                  if (!parsed) {
+                    throw new Error(t("settings.complex_fields.formula.expression_json_required"));
+                  }
+                },
+              },
+            ]}
+          >
+            <div>
+              {isDesktopOperatorPanel && (
+                <Flex justify="flex-end" style={{ marginBottom: 2 }}>
+                  <Tooltip
+                    title={
+                      showInlineOperatorPanel
+                        ? t("settings.complex_fields.formula.json_builder.hide_operators")
+                        : t("settings.complex_fields.formula.json_builder.show_operators")
+                    }
+                  >
+                    <Button
+                      type="default"
+                      size="small"
+                      icon={showInlineOperatorPanel ? <MenuFoldOutlined /> : <MenuUnfoldOutlined />}
+                      onClick={() => setOperatorPanelCollapsed((current) => !current)}
+                      aria-label={
+                        showInlineOperatorPanel
+                          ? t("settings.complex_fields.formula.json_builder.hide_operators")
+                          : t("settings.complex_fields.formula.json_builder.show_operators")
+                      }
+                    />
+                  </Tooltip>
+                </Flex>
+              )}
+              <Flex align="stretch" gap={8} wrap={false}>
+                <div style={{ flex: 1, minWidth: 0 }}>
+                  <div
+                    style={{
+                      // Keep editor + operators visually balanced by default, while still allowing
+                      // manual vertical resize for longer JSON authoring sessions.
+                      height: showInlineOperatorPanel ? INLINE_OPERATOR_PANEL_HEIGHT : 196,
+                      minHeight: showInlineOperatorPanel ? INLINE_OPERATOR_PANEL_HEIGHT : 196,
+                      resize: "vertical",
+                      overflow: "auto",
+                    }}
+                  >
+                    <CodeMirror
+                      value={expressionJsonValue || ""}
+                      // Keep CodeMirror bound to the container height so dragging the resize handle
+                      // expands the visible editor instead of adding blank space below it.
+                      height="100%"
+                      style={{
+                        height: "100%",
+                        backgroundColor: token.colorBgContainer,
+                        color: token.colorText,
+                      }}
+                      extensions={[json(), drawSelection(), codeMirrorTheme]}
+                      basicSetup={{
+                        lineNumbers: true,
+                        drawSelection: false,
+                        // Keep standard editor affordances on and theme them via codeMirrorTheme.
+                        bracketMatching: true,
+                        highlightSelectionMatches: true,
+                        highlightActiveLine: false,
+                        foldGutter: true,
+                      }}
+                      onCreateEditor={(editor) => {
+                        expressionJsonEditorRef.current = editor;
+                        const mainSelection = editor.state.selection.main;
+                        expressionJsonSelectionRef.current = { from: mainSelection.from, to: mainSelection.to };
+                      }}
+                      onUpdate={(viewUpdate) => {
+                        const mainSelection = viewUpdate.state.selection.main;
+                        expressionJsonSelectionRef.current = { from: mainSelection.from, to: mainSelection.to };
+                      }}
+                      onChange={(value) => {
+                        derivedForm.setFieldValue("expression_json", value);
+                      }}
+                    />
+                  </div>
+                  <Flex justify="flex-end" style={{ marginTop: 4, marginRight: 18 }}>
+                    <Tooltip title={t("settings.complex_fields.formula.json_builder.format_tooltip")}>
+                      <Button size="small" onClick={() => formatExpressionJson()}>
+                        {t("settings.complex_fields.formula.json_builder.format")}
+                      </Button>
+                    </Tooltip>
+                  </Flex>
+                </div>
+                {showInlineOperatorPanel && (
+                  <div
+                    style={{
+                      width: OPERATOR_PANEL_WIDTH,
+                      flex: `0 0 ${OPERATOR_PANEL_WIDTH}px`,
+                      ...tokenPanelStyle,
+                      padding: 8,
+                      height: INLINE_OPERATOR_PANEL_HEIGHT,
+                      minHeight: INLINE_OPERATOR_PANEL_HEIGHT,
+                      overflowY: "auto",
+                    }}
+                  >
+                    <Typography.Text type="secondary" style={{ display: "block", textAlign: "right" }}>
+                      <strong>{t("settings.complex_fields.formula.token_sections.operators")}</strong>
+                    </Typography.Text>
+                    <div style={{ marginTop: 8 }}>{renderOperatorTokenGroups(true)}</div>
+                  </div>
+                )}
+              </Flex>
+            </div>
+          </Form.Item>
+          {/* Show helper/operators before references so helper-first insertion flow is visually guided. */}
+          <Space
+            direction="vertical"
+            size={2}
+            style={{
+              width: "100%",
+              marginBottom: 8,
+            }}
+          >
+            <Flex justify="space-between" align="center">
+              <Space size={8} align="center">
+                <Typography.Text type="secondary">
+                  <strong>{t("settings.complex_fields.formula.json_builder.operators_title")}</strong>
+                </Typography.Text>
+                <Link
+                  style={{ fontSize: "0.85em" }}
+                  to="/help#formula-token-groups"
+                >
+                  {t("settings.complex_fields.help_links.formula_tokens")}
+                </Link>
+              </Space>
+            </Flex>
+            <div style={tokenPanelStyle}>
+              <Space direction="vertical" size={8} style={{ width: "100%" }}>
+                <div>
+                  <Flex justify="space-between" align="center" gap={8} wrap={false} style={{ height: 34 }}>
+                    <Typography.Text type="secondary">
+                      <strong>{t("settings.complex_fields.formula.token_sections.helper_functions")}</strong>
+                    </Typography.Text>
+                    {pendingHelperHint ? (
+                      <Space size={6} style={{ minWidth: 0, flexShrink: 0 }}>
+                        <Typography.Text type="warning" style={{ whiteSpace: "nowrap" }}>
+                          {t("settings.complex_fields.formula.json_builder.pending_helper_prefix")}
+                        </Typography.Text>
+                        <Typography.Text code style={{ color: token.colorWarningText }}>
+                          {pendingHelperHint.helper}
+                        </Typography.Text>
+                        <Typography.Text type="warning" style={{ whiteSpace: "nowrap" }}>
+                          {t("settings.complex_fields.formula.json_builder.pending_helper_count", {
+                            selected: pendingHelperHint.selected,
+                            total: pendingHelperHint.total,
+                          })}
+                        </Typography.Text>
+                        <Tooltip title={t("settings.complex_fields.formula.json_builder.cancel_pending_tooltip")}>
+                          <Button
+                            danger
+                            size="small"
+                            type="text"
+                            icon={<CloseCircleOutlined />}
+                            onClick={() => cancelPendingHelperInsert()}
+                            aria-label={t("settings.complex_fields.formula.json_builder.cancel_pending_tooltip")}
+                          />
+                        </Tooltip>
+                        <Tooltip title={t("settings.complex_fields.formula.json_builder.insert_without_reference_tooltip")}>
+                          <Button
+                            size="small"
+                            type="primary"
+                            onClick={() => insertPendingHelperWithoutReferences()}
+                            aria-label={t("settings.complex_fields.formula.json_builder.insert_without_reference_tooltip")}
+                          >
+                            {t("settings.complex_fields.formula.json_builder.helper_only")}
+                          </Button>
+                        </Tooltip>
+                      </Space>
+                    ) : null}
+                  </Flex>
+                  <div style={{ marginTop: 6 }}>{renderHelperTokenGroups(true)}</div>
+                </div>
+                <div style={{ paddingTop: 4 }}>
+                  <Typography.Text type="secondary">
+                    <strong>{t("settings.complex_fields.formula.reference_picker.label")}</strong>
+                  </Typography.Text>
+                  <div style={{ ...tokenCategoryStyle, marginTop: 6 }}>
+                    <div style={referenceGridStyle}>
+                      {compactReferenceOptions.map((reference) => {
+                        const referenceCompatible = isReferenceCompatibleWithPendingHelper(reference.value);
+                        const isSelectedForPendingHelper = Boolean(
+                          pendingJsonHelperInsert?.selectedReferences.includes(reference.value),
+                        );
+                        const disabledReason =
+                          !referenceCompatible && pendingHelperDefinition
+                            ? t("settings.complex_fields.formula.json_builder.reference_incompatible_reason", {
+                                helper: pendingHelperDefinition.name,
+                              })
+                            : null;
+                        const referenceToken = (
+                          <Typography.Text
+                            code
+                            style={{
+                              cursor: disabledReason ? "not-allowed" : "pointer",
+                              opacity: disabledReason ? 0.45 : 1,
+                              whiteSpace: "nowrap",
+                              overflow: "hidden",
+                              textOverflow: "ellipsis",
+                              textAlign: "center",
+                              fontWeight: 500,
+                              color: isSelectedForPendingHelper
+                                ? token.colorPrimaryText
+                                : (!disabledReason && hoveredTokenId === `reference-${reference.value}` ? token.colorWarningText : undefined),
+                              background:
+                                !disabledReason && hoveredTokenId === `reference-${reference.value}` ? token.colorWarningBg : undefined,
+                              borderColor:
+                                !disabledReason && hoveredTokenId === `reference-${reference.value}`
+                                  ? token.colorWarningBorder
+                                  : undefined,
+                              transition: "all 120ms ease-out",
+                            }}
+                            onMouseEnter={!disabledReason ? () => setHoveredTokenId(`reference-${reference.value}`) : undefined}
+                            onMouseLeave={!disabledReason ? () => setHoveredTokenId((current) => (current === `reference-${reference.value}` ? null : current)) : undefined}
+                            onClick={!disabledReason ? () => insertExpressionJsonReference(reference.value) : undefined}
+                          >
+                            {reference.label}
+                          </Typography.Text>
+                        );
+                        // Keep a stable wrapper shape for all reference tokens so disabled/tooltip states
+                        // do not cause reflow when helper compatibility changes.
+                        const content = (
+                          <Tooltip title={disabledReason || undefined}>
+                            <span style={{ display: "inline-flex", justifyContent: "center" }}>{referenceToken}</span>
+                          </Tooltip>
+                        );
+                        return (
+                          <div
+                            key={`reference-cell-${reference.value}`}
+                            style={{ display: "flex", justifyContent: "center", alignItems: "center", minHeight: 24 }}
+                          >
+                            {content}
+                          </div>
+                        );
+                      })}
+                    </div>
+                  </div>
+                </div>
+              </Space>
+            </div>
+            <Typography.Paragraph type="secondary" style={{ marginBottom: 0 }}>
+              {t("settings.complex_fields.formula.json_builder.click_to_insert_help")}
+            </Typography.Paragraph>
+          </Space>
+          <Form.Item
+            label={labeledField(
+              "settings.complex_fields.formula.sample_values",
+              "settings.complex_fields.formula.tooltips.sample_values",
+            )}
+            name="sample_values"
+            extra={t("settings.complex_fields.formula.sample_values_help")}
+            rules={[
+              {
+                validator: async (_, value) => {
+                  parseSampleValues(value);
+                },
+              },
+            ]}
+          >
+            <Input.TextArea
+              autoSize={{ minRows: 3, maxRows: 6 }}
+              placeholder={sampleValuesPlaceholder}
+              style={{ fontFamily: token.fontFamilyCode || "monospace" }}
+            />
+          </Form.Item>
+          <Space
+            direction="vertical"
+            size="middle"
+            style={{
+              width: "100%",
+            }}
+          >
+            <Flex justify="space-between" align="center" wrap="wrap" gap={12}>
+              <Button onClick={() => previewDerived()} loading={previewDerivedField.isPending}>
+                {t("settings.complex_fields.formula.preview.button")}
+              </Button>
+              <Flex align="center" gap={8} style={{ marginLeft: "auto" }}>
+                {labeledField(
+                  "settings.complex_fields.formula.columns.include_in_api",
+                  "settings.complex_fields.formula.tooltips.include_in_api",
+                )}
+                <Form.Item name="include_in_api" valuePropName="checked" style={{ marginBottom: 0 }}>
+                  <Switch />
+                </Form.Item>
+              </Flex>
+            </Flex>
+            {previewSummary}
+          </Space>
+        </Form>
+      </Modal>
+      {contextHolder}
+    </>
+  );
+}
diff --git a/client/src/pages/settings/extraFieldsSettings.tsx b/client/src/pages/settings/extraFieldsSettings.tsx
index 76599ea76..7902b3e72 100644
--- a/client/src/pages/settings/extraFieldsSettings.tsx
+++ b/client/src/pages/settings/extraFieldsSettings.tsx
@@ -3,6 +3,7 @@ import { useTranslate } from "@refinedev/core";
 import {
   Button,
   Checkbox,
+  Divider,
   Flex,
   Form,
   FormInstance,
@@ -12,7 +13,9 @@ import {
   Select,
   Space,
   Table,
+  Typography,
   message,
+  theme,
 } from "antd";
 import { FormItemProps, Rule } from "antd/es/form";
 import { ColumnType } from "antd/es/table";
@@ -20,12 +23,21 @@ import dayjs from "dayjs";
 import advancedFormat from "dayjs/plugin/advancedFormat";
 import timezone from "dayjs/plugin/timezone";
 import utc from "dayjs/plugin/utc";
-import { useState } from "react";
-import { Trans } from "react-i18next";
+import { useMemo, useState } from "react";
 import { useParams } from "react-router";
 import { DateTimePicker } from "../../components/dateTimePicker";
 import { InputNumberRange } from "../../components/inputNumberRange";
-import { EntityType, Field, FieldType, useDeleteField, useGetFields, useSetField } from "../../utils/queryFields";
+import { getExtraFieldReferences } from "../../utils/formulaFields";
+import { FormulaFieldsSettings } from "./complexFieldsSettings";
+import {
+  EntityType,
+  Field,
+  FieldType,
+  useDeleteField,
+  useGetDerivedFields,
+  useGetFields,
+  useSetField,
+} from "../../utils/queryFields";
 
 dayjs.extend(utc);
 dayjs.extend(timezone);
@@ -286,8 +298,10 @@ const EditableCell = ({ record, editing, dataIndex, children, form, ...restProps
 export function ExtraFieldsSettings() {
   const { entityType } = useParams<{ entityType: EntityType }>();
   const t = useTranslate();
+  const { token } = theme.useToken();
   const [form] = Form.useForm();
   const fields = useGetFields(entityType as EntityType);
+  const derivedFields = useGetDerivedFields(entityType as EntityType);
   const setField = useSetField(entityType as EntityType);
   const deleteField = useDeleteField(entityType as EntityType);
   const [isSubmitting, setIsSubmitting] = useState(false);
@@ -296,6 +310,7 @@ export function ExtraFieldsSettings() {
   const [messageApi, contextHolder] = message.useMessage();
 
   const [editingKey, setEditingKey] = useState("");
+  const sectionBodyStyle = { fontSize: token.fontSize, lineHeight: 1.7 };
 
   const isEditing = (record: FieldHolder) => record.field.key === editingKey;
 
@@ -443,7 +458,22 @@ export function ExtraFieldsSettings() {
   };
 
   const niceName = t(`${entityType}.${entityType}`);
-
+  const formulaDependenciesByCustomFieldKey = useMemo(() => {
+    const dependencies: Record<string, { key: string; name: string }[]> = {};
+    (derivedFields.data || []).forEach((derivedField) => {
+      const referencedCustomFields = getExtraFieldReferences(derivedField.expression_json || undefined);
+      referencedCustomFields.forEach((customFieldKey) => {
+        if (!dependencies[customFieldKey]) {
+          dependencies[customFieldKey] = [];
+        }
+        dependencies[customFieldKey].push({
+          key: derivedField.key,
+          name: derivedField.name,
+        });
+      });
+    });
+    return dependencies;
+  }, [derivedFields.data]);
   const columns: ColumnType<FieldHolder>[] = [
     {
       title: t("settings.extra_fields.params.key"),
@@ -547,18 +577,44 @@ export function ExtraFieldsSettings() {
               <Button disabled={editingKey !== ""} onClick={() => edit(record.field)} size="small">
                 {t("buttons.edit")}
               </Button>
-              <Popconfirm
-                title={t("settings.extra_fields.delete_confirm", { name: record.field.name })}
-                description={t("settings.extra_fields.delete_confirm_description", { name: record.field.name })}
-                onConfirm={() => del(record.field)}
-                disabled={editingKey !== ""}
-                okText={t("buttons.delete")}
-                cancelText={t("buttons.cancel")}
-              >
-                <Button disabled={editingKey !== ""} danger size="small">
-                  {t("buttons.delete")}
-                </Button>
-              </Popconfirm>
+              {(() => {
+                const formulaDependencies = formulaDependenciesByCustomFieldKey[record.field.key] || [];
+                const hasFormulaDependencies = formulaDependencies.length > 0;
+                const formulaDependencyList = formulaDependencies.map((item) => `${item.name} (${item.key})`).join(", ");
+                const confirmDescription = hasFormulaDependencies ? (
+                  <Space direction="vertical" size={4}>
+                    <Typography.Text>
+                      {t("settings.extra_fields.delete_confirm_description", { name: record.field.name })}
+                    </Typography.Text>
+                    <Typography.Text type="danger">{t("settings.extra_fields.delete_dependency_warning_intro")}</Typography.Text>
+                    {hasFormulaDependencies && (
+                      <Typography.Text code>
+                        {t("settings.extra_fields.delete_dependency_warning_formula", {
+                          dependencies: formulaDependencyList,
+                        })}
+                      </Typography.Text>
+                    )}
+                    <Typography.Text type="danger">{t("settings.extra_fields.delete_dependency_warning_footer")}</Typography.Text>
+                  </Space>
+                ) : (
+                  t("settings.extra_fields.delete_confirm_description", { name: record.field.name })
+                );
+
+                return (
+                  <Popconfirm
+                    title={t("settings.extra_fields.delete_confirm", { name: record.field.name })}
+                    description={confirmDescription}
+                    onConfirm={() => del(record.field)}
+                    disabled={editingKey !== ""}
+                    okText={t("buttons.delete")}
+                    cancelText={t("buttons.cancel")}
+                  >
+                    <Button disabled={editingKey !== ""} danger size="small">
+                      {t("buttons.delete")}
+                    </Button>
+                  </Popconfirm>
+                );
+              })()}
             </Space>
           </>
         );
@@ -601,12 +657,20 @@ export function ExtraFieldsSettings() {
       <h3>
         {t("settings.extra_fields.tab")} - {niceName}
       </h3>
-      <Trans
-        i18nKey={"settings.extra_fields.description"}
-        components={{
-          p: <p />,
-        }}
-      />
+      <Typography.Paragraph type="secondary" style={sectionBodyStyle}>
+        {t("settings.extra_fields.top_guidance")}
+      </Typography.Paragraph>
+      <Divider orientation="left" plain>
+        {t("settings.extra_fields.custom.header")}: {niceName}
+      </Divider>
+      <Typography.Paragraph type="secondary" style={sectionBodyStyle}>
+        {t("settings.extra_fields.custom.description_intro")} (
+        <Typography.Text code>text</Typography.Text>, <Typography.Text code>integer</Typography.Text>,{" "}
+        <Typography.Text code>integer_range</Typography.Text>, <Typography.Text code>float</Typography.Text>,{" "}
+        <Typography.Text code>float_range</Typography.Text>, <Typography.Text code>datetime</Typography.Text>,{" "}
+        <Typography.Text code>boolean</Typography.Text>, <Typography.Text code>choice</Typography.Text>).{" "}
+        {t("settings.extra_fields.custom.description_immutability")}
+      </Typography.Paragraph>
       <Form form={form} component={false} disabled={isSubmitting}>
         <Table
           components={{
@@ -635,6 +699,7 @@ export function ExtraFieldsSettings() {
           />
         </Flex>
       )}
+      <FormulaFieldsSettings />
       {contextHolder}
     </>
   );
diff --git a/client/src/pages/settings/index.tsx b/client/src/pages/settings/index.tsx
index 4393addfa..098a51c63 100644
--- a/client/src/pages/settings/index.tsx
+++ b/client/src/pages/settings/index.tsx
@@ -19,7 +19,6 @@ export const Settings = () => {
 
   const getCurrentKey = () => {
     const path = window.location.pathname.replace("/settings", "");
-    // Remove starting slash and ending slash if exists and return
     return path.replace(/^\/|\/$/g, "");
   };
 
diff --git a/client/src/pages/spools/list.tsx b/client/src/pages/spools/list.tsx
index 9ee11a3ed..e710f1368 100644
--- a/client/src/pages/spools/list.tsx
+++ b/client/src/pages/spools/list.tsx
@@ -11,6 +11,7 @@ import {
 import { List, useTable } from "@refinedev/antd";
 import { useInvalidate, useNavigation, useTranslate } from "@refinedev/core";
 import { Button, Dropdown, Modal, Table } from "antd";
+import { ColumnType } from "antd/es/table";
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc";
 import { useCallback, useMemo, useState } from "react";
@@ -27,6 +28,7 @@ import {
   SpoolIconColumn,
 } from "../../components/column";
 import { useLiveify } from "../../components/liveify";
+import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import {
   useSpoolmanFilamentFilter,
   useSpoolmanLocations,
@@ -34,7 +36,7 @@ import {
   useSpoolmanMaterials,
 } from "../../components/otherModels";
 import { removeUndefined } from "../../utils/filtering";
-import { EntityType, useGetFields } from "../../utils/queryFields";
+import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { TableState, useInitialTableState, useSavedState, useStoreInitialState } from "../../utils/saveload";
 import { useCurrencyFormatter } from "../../utils/settings";
 import { setSpoolArchived, useSpoolAdjustModal } from "./functions";
@@ -48,6 +50,7 @@ interface ISpoolCollapsed extends ISpool {
   "filament.combined_name": string; // Eg. "Prusa - PLA Red"
   "filament.id": number;
   "filament.material"?: string;
+  derived?: Record<string, unknown>;
 }
 
 function collapseSpool(element: ISpool): ISpoolCollapsed {
@@ -102,16 +105,17 @@ export const SpoolList = () => {
   const invalidate = useInvalidate();
   const navigate = useNavigate();
   const extraFields = useGetFields(EntityType.spool);
+  const formulaFields = useGetDerivedFields(EntityType.spool);
   const currencyFormatter = useCurrencyFormatter();
   const { openSpoolAdjustModal, spoolAdjustModal } = useSpoolAdjustModal();
 
-  const allColumnsWithExtraFields = [...allColumns, ...(extraFields.data?.map((field) => "extra." + field.key) ?? [])];
-
   // Load initial state
   const initialState = useInitialTableState(namespace);
 
   // State for the switch to show archived spools
   const [showArchived, setShowArchived] = useSavedState("spoolList-showArchived", false);
+  // Track formula-column hides separately so newly enabled toggleable fields still default to visible.
+  const [hiddenDerivedColumns, setHiddenDerivedColumns] = useSavedState<string[]>(`${namespace}-hiddenDerivedColumns`, []);
 
   // Fetch data from the API
   // To provide the live updates, we use a custom solution (useLiveify) instead of the built-in refine "liveMode" feature.
@@ -175,7 +179,41 @@ export const SpoolList = () => {
     () => (tableProps.dataSource || []).map((record) => ({ ...record })),
     [tableProps.dataSource],
   );
-  const dataSource = useLiveify("spool", queryDataSource, collapseSpool);
+  const liveDataSource = useLiveify("spool", queryDataSource, collapseSpool);
+  const listFormulaFields = useMemo(
+    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.list),
+    [formulaFields.data],
+  );
+  const toggleableListFormulaFields = useMemo(
+    () => listFormulaFields.filter((field) => field.allow_list_column_toggle),
+    [listFormulaFields],
+  );
+  const toggleableDerivedColumnKeys = useMemo(
+    () => toggleableListFormulaFields.map((field) => `derived.${field.key}`),
+    [toggleableListFormulaFields],
+  );
+  const allColumnsWithExtraFields = useMemo(
+    () => [
+      ...allColumns,
+      ...(extraFields.data?.map((field) => `extra.${field.key}`) ?? []),
+      ...toggleableDerivedColumnKeys,
+    ],
+    [extraFields.data, toggleableDerivedColumnKeys],
+  );
+  const selectedColumnKeys = useMemo(
+    () => [...showColumns, ...toggleableDerivedColumnKeys.filter((key) => !hiddenDerivedColumns.includes(key))],
+    [hiddenDerivedColumns, showColumns, toggleableDerivedColumnKeys],
+  );
+  const dataSource = useMemo<ISpoolCollapsed[]>(
+    () =>
+      liveDataSource.map((record) => ({
+        ...record,
+        // Formula values are computed client-side from the fetched row and are not persisted
+        // server-side fields, so they update on reload/live row updates and remain display-only.
+        derived: buildFormulaValues(record, listFormulaFields),
+      })),
+    [liveDataSource, listFormulaFields],
+  );
 
   // Function for opening an ant design modal that asks for confirmation for archiving a spool
   const archiveSpool = async (spool: ISpoolCollapsed, archive: boolean) => {
@@ -256,6 +294,11 @@ export const SpoolList = () => {
     sorter: true,
   };
 
+  const updateColumnSelections = (selectedKeys: string[]) => {
+    setShowColumns(selectedKeys.filter((key) => !toggleableDerivedColumnKeys.includes(key)));
+    setHiddenDerivedColumns(toggleableDerivedColumnKeys.filter((key) => !selectedKeys.includes(key)));
+  };
+
   return (
     <List
       headerButtons={({ defaultButtons }) => (
@@ -300,20 +343,27 @@ export const SpoolList = () => {
                     label: extraField?.name ?? column_id,
                   };
                 }
+                if (column_id.indexOf("derived.") === 0) {
+                  const formulaField = toggleableListFormulaFields.find((field) => `derived.${field.key}` === column_id);
+                  return {
+                    key: column_id,
+                    label: formulaField?.name ?? column_id,
+                  };
+                }
 
                 return {
                   key: column_id,
                   label: t(translateColumnI18nKey(column_id)),
                 };
               }),
-              selectedKeys: showColumns,
+              selectedKeys: selectedColumnKeys,
               selectable: true,
               multiple: true,
               onDeselect: (keys) => {
-                setShowColumns(keys.selectedKeys);
+                updateColumnSelections(keys.selectedKeys.map(String));
               },
               onSelect: (keys) => {
-                setShowColumns(keys.selectedKeys);
+                updateColumnSelections(keys.selectedKeys.map(String));
               },
             }}
           >
@@ -457,6 +507,21 @@ export const SpoolList = () => {
               field,
             });
           }) ?? []),
+          ...listFormulaFields.map(
+            (field) => {
+              const derivedColumnKey = `derived.${field.key}`;
+              if (field.allow_list_column_toggle && hiddenDerivedColumns.includes(derivedColumnKey)) {
+                return undefined;
+              }
+
+              return {
+                key: derivedColumnKey,
+                title: field.name,
+                width: 140,
+                render: (_: unknown, record: ISpoolCollapsed) => formatFormulaValue(record.derived?.[field.key]),
+              } as ColumnType<ISpoolCollapsed>;
+            },
+          ),
           RichColumn({
             ...commonProps,
             id: "comment",
diff --git a/client/src/pages/spools/show.tsx b/client/src/pages/spools/show.tsx
index 9f6ba59d6..e86a70c93 100644
--- a/client/src/pages/spools/show.tsx
+++ b/client/src/pages/spools/show.tsx
@@ -1,3 +1,4 @@
+import { Fragment, useMemo } from "react";
 import { InboxOutlined, PrinterOutlined, ToTopOutlined, ToolOutlined } from "@ant-design/icons";
 import { DateField, NumberField, Show, TextField } from "@refinedev/antd";
 import { useInvalidate, useShow, useTranslate } from "@refinedev/core";
@@ -7,8 +8,9 @@ import utc from "dayjs/plugin/utc";
 import { ExtraFieldDisplay } from "../../components/extraFields";
 import { NumberFieldUnit } from "../../components/numberField";
 import SpoolIcon from "../../components/spoolIcon";
+import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import { enrichText } from "../../utils/parsing";
-import { EntityType, useGetFields } from "../../utils/queryFields";
+import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { useCurrencyFormatter } from "../../utils/settings";
 import { getBasePath } from "../../utils/url";
 import { IFilament } from "../filaments/model";
@@ -23,6 +25,7 @@ const { confirm } = Modal;
 export const SpoolShow = () => {
   const t = useTranslate();
   const extraFields = useGetFields(EntityType.spool);
+  const formulaFields = useGetDerivedFields(EntityType.spool);
   const currencyFormatter = useCurrencyFormatter();
   const invalidate = useInvalidate();
 
@@ -32,6 +35,14 @@ export const SpoolShow = () => {
   const { data, isLoading } = query;
 
   const record = data?.data;
+  const showFormulaFields = useMemo(
+    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.show),
+    [formulaFields.data],
+  );
+  const derivedValues = useMemo(
+    () => (record ? buildFormulaValues(record, showFormulaFields) : {}),
+    [record, showFormulaFields],
+  );
 
   const spoolPrice = (item?: ISpool) => {
     const price = item?.price ?? item?.filament.price;
@@ -223,6 +234,13 @@ export const SpoolShow = () => {
       {extraFields?.data?.map((field, index) => (
         <ExtraFieldDisplay key={index} field={field} value={record?.extra[field.key]} />
       ))}
+      {showFormulaFields.length > 0 && <Title level={4}>{t("settings.complex_fields.formula.header")}</Title>}
+      {showFormulaFields.map((field) => (
+        <Fragment key={field.key}>
+          <Title level={5}>{field.name}</Title>
+          <TextField value={formatFormulaValue(derivedValues[field.key])} />
+        </Fragment>
+      ))}
     </Show>
   );
 };
diff --git a/client/src/pages/vendors/list.tsx b/client/src/pages/vendors/list.tsx
index 8fc3cb468..7ceb000c0 100644
--- a/client/src/pages/vendors/list.tsx
+++ b/client/src/pages/vendors/list.tsx
@@ -2,6 +2,7 @@ import { EditOutlined, EyeOutlined, FilterOutlined, PlusSquareOutlined } from "@
 import { List, useTable } from "@refinedev/antd";
 import { useInvalidate, useNavigation, useTranslate } from "@refinedev/core";
 import { Button, Dropdown, Table } from "antd";
+import { ColumnType } from "antd/es/table";
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc";
 import { useCallback, useMemo, useState } from "react";
@@ -15,9 +16,10 @@ import {
   SortedColumn,
 } from "../../components/column";
 import { useLiveify } from "../../components/liveify";
+import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import { removeUndefined } from "../../utils/filtering";
-import { EntityType, useGetFields } from "../../utils/queryFields";
-import { TableState, useInitialTableState, useStoreInitialState } from "../../utils/saveload";
+import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
+import { TableState, useInitialTableState, useSavedState, useStoreInitialState } from "../../utils/saveload";
 import { IVendor } from "./model";
 
 dayjs.extend(utc);
@@ -31,11 +33,12 @@ export const VendorList = () => {
   const invalidate = useInvalidate();
   const navigate = useNavigate();
   const extraFields = useGetFields(EntityType.vendor);
-
-  const allColumnsWithExtraFields = [...allColumns, ...(extraFields.data?.map((field) => "extra." + field.key) ?? [])];
+  const formulaFields = useGetDerivedFields(EntityType.vendor);
 
   // Load initial state
   const initialState = useInitialTableState(namespace);
+  // Track formula-column hides separately so newly enabled toggleable fields still default to visible.
+  const [hiddenDerivedColumns, setHiddenDerivedColumns] = useSavedState<string[]>(`${namespace}-hiddenDerivedColumns`, []);
 
   // Fetch data from the API
   const { tableProps, sorters, setSorters, filters, setFilters, currentPage, pageSize, setCurrentPage } =
@@ -82,11 +85,45 @@ export const VendorList = () => {
   const queryDataSource: IVendor[] = useMemo(() => {
     return (tableProps.dataSource || []).map((record) => ({ ...record }));
   }, [tableProps.dataSource]);
-  const dataSource = useLiveify(
+  const liveDataSource = useLiveify(
     "vendor",
     queryDataSource,
     useCallback((record: IVendor) => record, []),
   );
+  const listFormulaFields = useMemo(
+    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.list),
+    [formulaFields.data],
+  );
+  const toggleableListFormulaFields = useMemo(
+    () => listFormulaFields.filter((field) => field.allow_list_column_toggle),
+    [listFormulaFields],
+  );
+  const toggleableDerivedColumnKeys = useMemo(
+    () => toggleableListFormulaFields.map((field) => `derived.${field.key}`),
+    [toggleableListFormulaFields],
+  );
+  const allColumnsWithExtraFields = useMemo(
+    () => [
+      ...allColumns,
+      ...(extraFields.data?.map((field) => `extra.${field.key}`) ?? []),
+      ...toggleableDerivedColumnKeys,
+    ],
+    [extraFields.data, toggleableDerivedColumnKeys],
+  );
+  const selectedColumnKeys = useMemo(
+    () => [...showColumns, ...toggleableDerivedColumnKeys.filter((key) => !hiddenDerivedColumns.includes(key))],
+    [hiddenDerivedColumns, showColumns, toggleableDerivedColumnKeys],
+  );
+  const dataSource = useMemo<IVendor[]>(
+    () =>
+      liveDataSource.map((record) => ({
+        ...record,
+        // Formula values are computed client-side from the fetched row and are not persisted
+        // server-side fields, so they update on reload/live row updates and remain display-only.
+        derived: buildFormulaValues(record, listFormulaFields),
+      })),
+    [liveDataSource, listFormulaFields],
+  );
 
   if (tableProps.pagination) {
     tableProps.pagination.showSizeChanger = true;
@@ -108,6 +145,11 @@ export const VendorList = () => {
     sorter: true,
   };
 
+  const updateColumnSelections = (selectedKeys: string[]) => {
+    setShowColumns(selectedKeys.filter((key) => !toggleableDerivedColumnKeys.includes(key)));
+    setHiddenDerivedColumns(toggleableDerivedColumnKeys.filter((key) => !selectedKeys.includes(key)));
+  };
+
   return (
     <List
       headerButtons={({ defaultButtons }) => (
@@ -134,20 +176,27 @@ export const VendorList = () => {
                     label: extraField?.name ?? column_id,
                   };
                 }
+                if (column_id.indexOf("derived.") === 0) {
+                  const formulaField = toggleableListFormulaFields.find((field) => `derived.${field.key}` === column_id);
+                  return {
+                    key: column_id,
+                    label: formulaField?.name ?? column_id,
+                  };
+                }
 
                 return {
                   key: column_id,
                   label: t(`vendor.fields.${column_id}`),
                 };
               }),
-              selectedKeys: showColumns,
+              selectedKeys: selectedColumnKeys,
               selectable: true,
               multiple: true,
               onDeselect: (keys) => {
-                setShowColumns(keys.selectedKeys);
+                updateColumnSelections(keys.selectedKeys.map(String));
               },
               onSelect: (keys) => {
-                setShowColumns(keys.selectedKeys);
+                updateColumnSelections(keys.selectedKeys.map(String));
               },
             }}
           >
@@ -198,6 +247,22 @@ export const VendorList = () => {
               field,
             });
           }) ?? []),
+          ...listFormulaFields.map(
+            (field) => {
+              const derivedColumnKey = `derived.${field.key}`;
+              if (field.allow_list_column_toggle && hiddenDerivedColumns.includes(derivedColumnKey)) {
+                return undefined;
+              }
+
+              return {
+                key: derivedColumnKey,
+                title: field.name,
+                width: 140,
+                render: (_: unknown, record: IVendor) =>
+                  formatFormulaValue((record as IVendor & { derived?: Record<string, unknown> }).derived?.[field.key]),
+              } as ColumnType<IVendor>;
+            },
+          ),
           RichColumn({
             ...commonProps,
             id: "comment",
diff --git a/client/src/pages/vendors/show.tsx b/client/src/pages/vendors/show.tsx
index 1fc49110a..9404c2c55 100644
--- a/client/src/pages/vendors/show.tsx
+++ b/client/src/pages/vendors/show.tsx
@@ -1,11 +1,13 @@
+import { Fragment, useMemo } from "react";
 import { DateField, NumberField, Show, TextField } from "@refinedev/antd";
 import { useShow, useTranslate } from "@refinedev/core";
 import { Typography } from "antd";
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc";
 import { ExtraFieldDisplay } from "../../components/extraFields";
+import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import { enrichText } from "../../utils/parsing";
-import { EntityType, useGetFields } from "../../utils/queryFields";
+import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { IVendor } from "./model";
 
 dayjs.extend(utc);
@@ -15,6 +17,7 @@ const { Title } = Typography;
 export const VendorShow = () => {
   const t = useTranslate();
   const extraFields = useGetFields(EntityType.vendor);
+  const formulaFields = useGetDerivedFields(EntityType.vendor);
 
   const { query } = useShow<IVendor>({
     liveMode: "auto",
@@ -22,6 +25,14 @@ export const VendorShow = () => {
   const { data, isLoading } = query;
 
   const record = data?.data;
+  const showFormulaFields = useMemo(
+    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.show),
+    [formulaFields.data],
+  );
+  const derivedValues = useMemo(
+    () => (record ? buildFormulaValues(record, showFormulaFields) : {}),
+    [record, showFormulaFields],
+  );
 
   const formatTitle = (item: IVendor) => {
     return t("vendor.titles.show_title", { id: item.id, name: item.name, interpolation: { escapeValue: false } });
@@ -49,6 +60,13 @@ export const VendorShow = () => {
       {extraFields?.data?.map((field, index) => (
         <ExtraFieldDisplay key={index} field={field} value={record?.extra[field.key]} />
       ))}
+      {showFormulaFields.length > 0 && <Title level={4}>{t("settings.complex_fields.formula.header")}</Title>}
+      {showFormulaFields.map((field) => (
+        <Fragment key={field.key}>
+          <Title level={5}>{field.name}</Title>
+          <TextField value={formatFormulaValue(derivedValues[field.key])} />
+        </Fragment>
+      ))}
     </Show>
   );
 };
diff --git a/client/src/utils/formulaFields.ts b/client/src/utils/formulaFields.ts
new file mode 100644
index 000000000..95c04cfb9
--- /dev/null
+++ b/client/src/utils/formulaFields.ts
@@ -0,0 +1,536 @@
+import { ComplexFieldSurface, DerivedField } from "./queryFields";
+
+type FormulaScope = object;
+
+export type FormulaHelperDefinition = {
+  name: string;
+  description: string;
+  category: FormulaHelperCategory;
+  insert_mode?: "reference" | "none";
+  reference_count?: number;
+  reference_kind?: "any" | "number" | "datetime" | "text";
+};
+
+export type FormulaHelperCategory = "math" | "text" | "datetime" | "dynamic" | "date_diff" | "color";
+
+export type FormulaHelperGroupDefinition = {
+  key: FormulaHelperCategory;
+  helpers: FormulaHelperDefinition[];
+};
+
+export const FORMULA_HELPERS: FormulaHelperDefinition[] = [
+  { name: "abs", description: "Returns the absolute value of a number.", category: "math", reference_kind: "number" },
+  { name: "min", description: "Returns the smallest value from the provided arguments.", category: "math", reference_kind: "number" },
+  { name: "max", description: "Returns the largest value from the provided arguments.", category: "math", reference_kind: "number" },
+  { name: "round", description: "Rounds a numeric value to the nearest integer.", category: "math", reference_kind: "number" },
+  { name: "coalesce", description: "Returns the first argument that is not null/undefined.", category: "math", reference_kind: "any" },
+  { name: "cat", description: "Concatenates values as text.", category: "text", reference_kind: "any" },
+  { name: "upper", description: "Converts text to uppercase.", category: "text", reference_kind: "text" },
+  { name: "lower", description: "Converts text to lowercase.", category: "text", reference_kind: "text" },
+  { name: "trim", description: "Removes leading/trailing whitespace from text.", category: "text", reference_kind: "text" },
+  { name: "length", description: "Returns text length.", category: "text", reference_kind: "text" },
+  { name: "left", description: "Returns left-most text characters (optional count, default 1).", category: "text", reference_kind: "text" },
+  { name: "right", description: "Returns right-most text characters (optional count, default 1).", category: "text", reference_kind: "text" },
+  { name: "year", description: "Extracts UTC year from a date/datetime value.", category: "datetime", reference_kind: "datetime" },
+  { name: "month", description: "Extracts UTC month (1-12) from a date/datetime value.", category: "datetime", reference_kind: "datetime" },
+  { name: "day", description: "Extracts UTC day-of-month from a date/datetime value.", category: "datetime", reference_kind: "datetime" },
+  { name: "hour", description: "Extracts UTC hour from a date/datetime value.", category: "datetime", reference_kind: "datetime" },
+  { name: "minute", description: "Extracts UTC minute from a date/datetime value.", category: "datetime", reference_kind: "datetime" },
+  { name: "second", description: "Extracts UTC second from a date/datetime value.", category: "datetime", reference_kind: "datetime" },
+  { name: "timestamp", description: "Converts a date/datetime value to Unix timestamp seconds.", category: "datetime", reference_kind: "datetime" },
+  { name: "date_only", description: "Formats a date/datetime as YYYY-MM-DD (UTC).", category: "datetime", reference_kind: "datetime" },
+  { name: "time_only", description: "Formats a date/datetime as HH:MM:SS (UTC).", category: "datetime", reference_kind: "datetime" },
+  {
+    name: "days_between",
+    description: "Returns day difference between start and end date/datetime values.",
+    category: "date_diff",
+    reference_count: 2,
+    reference_kind: "datetime",
+  },
+  {
+    name: "hours_between",
+    description: "Returns hour difference between start and end date/datetime values.",
+    category: "date_diff",
+    reference_count: 2,
+    reference_kind: "datetime",
+  },
+  {
+    name: "hue_from_hex",
+    description: "Returns hue angle (0-360) for a hex color string.",
+    category: "color",
+    reference_kind: "text",
+  },
+  { name: "today", description: "Returns current UTC date as YYYY-MM-DD.", category: "dynamic", insert_mode: "none" },
+];
+
+export const FORMULA_HELPER_GROUP_ORDER: FormulaHelperCategory[] = ["math", "text", "datetime", "dynamic", "date_diff", "color"];
+
+export const FORMULA_HELPER_GROUPS: FormulaHelperGroupDefinition[] = FORMULA_HELPER_GROUP_ORDER.map((key) => ({
+  key,
+  helpers: FORMULA_HELPERS.filter((helper) => helper.category === key),
+}));
+
+function coalesce(...values: unknown[]) {
+  return values.find((value) => value !== null && value !== undefined) ?? null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function asDate(value: unknown): Date {
+  if (value instanceof Date) {
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "number") {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.valueOf())) {
+      return parsed;
+    }
+  }
+  throw new Error("Value is not a date/datetime.");
+}
+
+function pad(value: number): string {
+  return value.toString().padStart(2, "0");
+}
+
+function dateOnly(value: unknown): string {
+  const parsed = asDate(value);
+  return `${parsed.getUTCFullYear()}-${pad(parsed.getUTCMonth() + 1)}-${pad(parsed.getUTCDate())}`;
+}
+
+function timeOnly(value: unknown): string {
+  const parsed = asDate(value);
+  return `${pad(parsed.getUTCHours())}:${pad(parsed.getUTCMinutes())}:${pad(parsed.getUTCSeconds())}`;
+}
+
+function daysBetween(start: unknown, end: unknown): number {
+  return (asDate(end).valueOf() - asDate(start).valueOf()) / 86400000;
+}
+
+function hoursBetween(start: unknown, end: unknown): number {
+  return (asDate(end).valueOf() - asDate(start).valueOf()) / 3600000;
+}
+
+function hueFromHex(value: unknown): number {
+  if (typeof value !== "string") {
+    throw new Error("hue_from_hex expects a color string.");
+  }
+
+  let normalized = value.trim().replace(/^#/, "");
+  if (normalized.length === 3) {
+    normalized = normalized
+      .split("")
+      .map((char) => char + char)
+      .join("");
+  }
+  if (normalized.length !== 6) {
+    throw new Error("hue_from_hex expects a 3 or 6 digit hex color.");
+  }
+
+  const red = parseInt(normalized.slice(0, 2), 16) / 255;
+  const green = parseInt(normalized.slice(2, 4), 16) / 255;
+  const blue = parseInt(normalized.slice(4, 6), 16) / 255;
+
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+
+  if (delta === 0) {
+    return 0;
+  }
+
+  let hue = 0;
+  if (max === red) {
+    hue = ((green - blue) / delta) % 6;
+  } else if (max === green) {
+    hue = (blue - red) / delta + 2;
+  } else {
+    hue = (red - green) / delta + 4;
+  }
+
+  const degrees = hue * 60;
+  return Math.round((((degrees % 360) + 360) % 360) * 1000) / 1000;
+}
+
+function today(): string {
+  return dateOnly(new Date());
+}
+
+function normalizeJsonLogicArgs(rawValue: unknown): unknown[] {
+  if (Array.isArray(rawValue)) {
+    return rawValue;
+  }
+  return [rawValue];
+}
+
+function asNumber(value: unknown, operator: string): number {
+  const parsed = Number(value);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`${operator} expects numeric values.`);
+  }
+  return parsed;
+}
+
+function parseExtraValue(value: unknown): unknown {
+  if (typeof value !== "string") {
+    return value;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function getReferenceValue(reference: string, scope: FormulaScope): unknown {
+  const parts = reference.split(".");
+  let current: unknown = scope;
+
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index];
+    if (current === null || current === undefined || typeof current !== "object") {
+      return undefined;
+    }
+
+    const record = current as Record<string, unknown>;
+    if (!(part in record)) {
+      return undefined;
+    }
+
+    current = record[part];
+    if (parts[index] === "extra") {
+      // Extra fields are still stored as JSON strings in API payloads, so derived formulas need to
+      // unwrap them lazily when a reference walks into the extra.* namespace.
+      current = parseExtraValue(current);
+    }
+  }
+
+  return current;
+}
+
+function collectFormulaReferencesFromJsonLogic(node: unknown, references: Set<string>): void {
+  if (node === null || typeof node === "string" || typeof node === "number" || typeof node === "boolean") {
+    return;
+  }
+  if (Array.isArray(node)) {
+    node.forEach((value) => collectFormulaReferencesFromJsonLogic(value, references));
+    return;
+  }
+  if (!isRecord(node)) {
+    return;
+  }
+
+  const entries = Object.entries(node);
+  if (entries.length !== 1) {
+    return;
+  }
+  const [operator, rawArgs] = entries[0];
+  const args = normalizeJsonLogicArgs(rawArgs);
+
+  if (operator === "var") {
+    const reference = args[0];
+    if (typeof reference === "string" && reference !== "") {
+      references.add(reference);
+    }
+    if (args.length > 1) {
+      collectFormulaReferencesFromJsonLogic(args[1], references);
+    }
+    return;
+  }
+
+  args.forEach((arg) => collectFormulaReferencesFromJsonLogic(arg, references));
+}
+
+export function getFormulaReferencesFromJsonLogic(expressionJson: Record<string, unknown>): string[] {
+  const references = new Set<string>();
+  collectFormulaReferencesFromJsonLogic(expressionJson, references);
+  return [...references];
+}
+
+export function getExtraFieldReferences(expressionJson?: Record<string, unknown> | null): string[] {
+  const references = new Set<string>();
+  if (expressionJson) {
+    getFormulaReferencesFromJsonLogic(expressionJson).forEach((reference) => references.add(reference));
+  }
+  const extraReferences = [...references]
+    .filter((reference) => reference.startsWith("extra."))
+    .map((reference) => reference.slice("extra.".length))
+    .filter((reference) => reference.length > 0);
+  return [...new Set(extraReferences)];
+}
+
+function lookupJsonLogicReference(reference: unknown, scope: FormulaScope, defaultValue: unknown): unknown {
+  const scopeRecord = scope as Record<string, unknown>;
+  if (typeof reference === "number") {
+    return scopeRecord[String(reference)] ?? defaultValue;
+  }
+  if (typeof reference !== "string") {
+    throw new Error("JSON Logic var reference must be a string or integer.");
+  }
+  if (reference === "") {
+    return scope;
+  }
+
+  const value = getReferenceValue(reference, scope);
+  return value === undefined ? defaultValue : value;
+}
+
+function truthy(value: unknown): boolean {
+  return Boolean(value);
+}
+
+export function evaluateFormulaJsonLogic(expressionJson: Record<string, unknown>, scope: FormulaScope): unknown {
+  const evaluateNode = (node: unknown): unknown => {
+    if (node === null || typeof node === "string" || typeof node === "number" || typeof node === "boolean") {
+      return node;
+    }
+    if (Array.isArray(node)) {
+      return node.map((value) => evaluateNode(value));
+    }
+    if (!isRecord(node)) {
+      throw new Error("JSON Logic expression contains unsupported value types.");
+    }
+
+    const entries = Object.entries(node);
+    if (entries.length !== 1) {
+      throw new Error("JSON Logic expression objects must contain exactly one operator.");
+    }
+
+    const [operator, rawArgs] = entries[0];
+    const args = normalizeJsonLogicArgs(rawArgs);
+
+    if (operator === "var") {
+      const reference = args[0] ?? "";
+      const defaultValue = args.length > 1 ? evaluateNode(args[1]) : null;
+      return lookupJsonLogicReference(reference, scope, defaultValue);
+    }
+
+    if (operator === "if") {
+      if (args.length < 2) {
+        throw new Error("JSON Logic if operator requires at least 2 arguments.");
+      }
+      for (let index = 0; index < args.length - 1; index += 2) {
+        if (truthy(evaluateNode(args[index]))) {
+          return evaluateNode(args[index + 1]);
+        }
+      }
+      if (args.length % 2 === 1) {
+        return evaluateNode(args[args.length - 1]);
+      }
+      return null;
+    }
+
+    if (operator === "and") {
+      let result: unknown = true;
+      args.forEach((arg) => {
+        if (!truthy(result)) {
+          return;
+        }
+        result = evaluateNode(arg);
+      });
+      return result;
+    }
+
+    if (operator === "or") {
+      let result: unknown = false;
+      args.forEach((arg) => {
+        if (truthy(result)) {
+          return;
+        }
+        result = evaluateNode(arg);
+      });
+      return result;
+    }
+
+    if (operator === "!") {
+      if (args.length !== 1) {
+        throw new Error("JSON Logic ! operator requires one argument.");
+      }
+      return !truthy(evaluateNode(args[0]));
+    }
+
+    const evaluatedArgs = args.map((arg) => evaluateNode(arg));
+
+    if (operator === "==") {
+      return evaluatedArgs[0] === evaluatedArgs[1];
+    }
+    if (operator === "!=") {
+      return evaluatedArgs[0] !== evaluatedArgs[1];
+    }
+    if (operator === "<") {
+      return (evaluatedArgs[0] as number) < (evaluatedArgs[1] as number);
+    }
+    if (operator === "<=") {
+      return (evaluatedArgs[0] as number) <= (evaluatedArgs[1] as number);
+    }
+    if (operator === ">") {
+      return (evaluatedArgs[0] as number) > (evaluatedArgs[1] as number);
+    }
+    if (operator === ">=") {
+      return (evaluatedArgs[0] as number) >= (evaluatedArgs[1] as number);
+    }
+    if (operator === "+") {
+      return evaluatedArgs.reduce<number>((sum, value) => sum + asNumber(value, "+"), 0);
+    }
+    if (operator === "-") {
+      if (evaluatedArgs.length === 1) {
+        return -asNumber(evaluatedArgs[0], "-");
+      }
+      return asNumber(evaluatedArgs[0], "-") - asNumber(evaluatedArgs[1], "-");
+    }
+    if (operator === "*") {
+      return evaluatedArgs.reduce<number>((product, value) => product * asNumber(value, "*"), 1);
+    }
+    if (operator === "/") {
+      if (evaluatedArgs.length !== 2) {
+        throw new Error("JSON Logic / operator requires two arguments.");
+      }
+      return asNumber(evaluatedArgs[0], "/") / asNumber(evaluatedArgs[1], "/");
+    }
+    if (operator === "%") {
+      return asNumber(evaluatedArgs[0], "%") % asNumber(evaluatedArgs[1], "%");
+    }
+    if (operator === "min") {
+      return Math.min(...evaluatedArgs.map((value) => asNumber(value, "min")));
+    }
+    if (operator === "max") {
+      return Math.max(...evaluatedArgs.map((value) => asNumber(value, "max")));
+    }
+    if (operator === "round") {
+      return Math.round(asNumber(evaluatedArgs[0], "round"));
+    }
+    if (operator === "floor") {
+      return Math.floor(asNumber(evaluatedArgs[0], "floor"));
+    }
+    if (operator === "ceil") {
+      return Math.ceil(asNumber(evaluatedArgs[0], "ceil"));
+    }
+    if (operator === "abs") {
+      return Math.abs(asNumber(evaluatedArgs[0], "abs"));
+    }
+    if (operator === "cat") {
+      return evaluatedArgs.map((value) => `${value ?? ""}`).join("");
+    }
+    if (operator === "upper") {
+      return `${evaluatedArgs[0] ?? ""}`.toUpperCase();
+    }
+    if (operator === "lower") {
+      return `${evaluatedArgs[0] ?? ""}`.toLowerCase();
+    }
+    if (operator === "trim") {
+      return `${evaluatedArgs[0] ?? ""}`.trim();
+    }
+    if (operator === "length") {
+      const value = evaluatedArgs[0];
+      if (typeof value === "string" || Array.isArray(value)) {
+        return value.length;
+      }
+      if (isRecord(value)) {
+        return Object.keys(value).length;
+      }
+      throw new Error("length expects string, array, or object.");
+    }
+    if (operator === "replace") {
+      return `${evaluatedArgs[0] ?? ""}`.replace(`${evaluatedArgs[1] ?? ""}`, `${evaluatedArgs[2] ?? ""}`);
+    }
+    if (operator === "left") {
+      const value = `${evaluatedArgs[0] ?? ""}`;
+      const count = evaluatedArgs.length > 1 ? asNumber(evaluatedArgs[1], "left") : 1;
+      const length = Math.max(0, Math.floor(count));
+      return value.slice(0, length);
+    }
+    if (operator === "right") {
+      const value = `${evaluatedArgs[0] ?? ""}`;
+      const count = evaluatedArgs.length > 1 ? asNumber(evaluatedArgs[1], "right") : 1;
+      const length = Math.max(0, Math.floor(count));
+      if (length === 0) {
+        return "";
+      }
+      return value.slice(-length);
+    }
+    if (operator === "coalesce") {
+      return coalesce(...evaluatedArgs);
+    }
+    if (operator === "today") {
+      return today();
+    }
+    if (operator === "year") {
+      return asDate(evaluatedArgs[0]).getUTCFullYear();
+    }
+    if (operator === "month") {
+      return asDate(evaluatedArgs[0]).getUTCMonth() + 1;
+    }
+    if (operator === "day") {
+      return asDate(evaluatedArgs[0]).getUTCDate();
+    }
+    if (operator === "hour") {
+      return asDate(evaluatedArgs[0]).getUTCHours();
+    }
+    if (operator === "minute") {
+      return asDate(evaluatedArgs[0]).getUTCMinutes();
+    }
+    if (operator === "second") {
+      return asDate(evaluatedArgs[0]).getUTCSeconds();
+    }
+    if (operator === "timestamp") {
+      return asDate(evaluatedArgs[0]).valueOf() / 1000;
+    }
+    if (operator === "date_only") {
+      return dateOnly(evaluatedArgs[0]);
+    }
+    if (operator === "time_only") {
+      return timeOnly(evaluatedArgs[0]);
+    }
+    if (operator === "days_between") {
+      return daysBetween(evaluatedArgs[0], evaluatedArgs[1]);
+    }
+    if (operator === "hours_between") {
+      return hoursBetween(evaluatedArgs[0], evaluatedArgs[1]);
+    }
+    if (operator === "hue_from_hex") {
+      return hueFromHex(evaluatedArgs[0]);
+    }
+
+    throw new Error(`JSON Logic operator '${operator}' is not implemented.`);
+  };
+
+  return evaluateNode(expressionJson);
+}
+
+export function getTemplateFormulaFields(fields: DerivedField[] | undefined): DerivedField[] {
+  return (fields || []).filter((field) => field.surfaces.includes(ComplexFieldSurface.template));
+}
+
+export function getFormulaFieldsForSurface(
+  fields: DerivedField[] | undefined,
+  surface: ComplexFieldSurface,
+): DerivedField[] {
+  return (fields || []).filter((field) => field.surfaces.includes(surface));
+}
+
+export function buildFormulaValues(scope: FormulaScope, fields: DerivedField[]): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  fields.forEach((field) => {
+    try {
+      if (field.expression_json) {
+        values[field.key] = evaluateFormulaJsonLogic(field.expression_json, scope);
+      }
+    } catch {
+      // Failed evaluations stay hidden so one invalid formula does not break show/list/template
+      // rendering for the rest of the entity payload.
+    }
+  });
+  return values;
+}
+
+export function formatFormulaValue(value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return `${value}`;
+  }
+  return JSON.stringify(value);
+}
diff --git a/client/src/utils/queryFields.ts b/client/src/utils/queryFields.ts
index 7cde38c05..9b3fe6f89 100644
--- a/client/src/utils/queryFields.ts
+++ b/client/src/utils/queryFields.ts
@@ -19,6 +19,15 @@ export enum EntityType {
   spool = "spool",
 }
 
+export enum ComplexFieldSurface {
+  show = "show",
+  edit = "edit",
+  list = "list",
+  template = "template",
+  action = "action",
+  derived = "derived",
+}
+
 export interface FieldParameters {
   name: string;
   order: number;
@@ -34,6 +43,31 @@ export interface Field extends FieldParameters {
   entity_type: EntityType;
 }
 
+export enum DerivedFieldType {
+  number = "number",
+  text = "text",
+}
+
+export interface DerivedFieldParameters {
+  name: string;
+  description?: string;
+  result_type: DerivedFieldType;
+  expression_json: Record<string, unknown>;
+  surfaces: string[];
+  allow_list_column_toggle: boolean;
+  include_in_api: boolean;
+}
+
+export interface DerivedField extends DerivedFieldParameters {
+  key: string;
+  entity_type: EntityType;
+}
+
+export interface DerivedFieldPreview {
+  result: string | number | boolean | null;
+  references: string[];
+}
+
 export function useGetFields(entity_type: EntityType) {
   return useQuery<Field[]>({
     queryKey: ["fields", entity_type],
@@ -134,3 +168,90 @@ export function useDeleteField(entity_type: EntityType) {
     },
   });
 }
+
+export function useGetDerivedFields(entity_type: EntityType) {
+  return useQuery<DerivedField[]>({
+    queryKey: ["derivedFields", entity_type],
+    queryFn: async () => {
+      const response = await fetch(`${getAPIURL()}/field/derived/${entity_type}`);
+      return response.json();
+    },
+  });
+}
+
+export function useSetDerivedField(entity_type: EntityType) {
+  const queryClient = useQueryClient();
+
+  return useMutation<DerivedField[], unknown, { key: string; params: DerivedFieldParameters }>({
+    mutationFn: async ({ key, params }) => {
+      const response = await fetch(`${getAPIURL()}/field/derived/${entity_type}/${key}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(params),
+      });
+
+      if (!response.ok) {
+        throw new Error((await response.json()).message);
+      }
+
+      return response.json();
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: ["derivedFields", entity_type],
+      });
+    },
+  });
+}
+
+export function useDeleteDerivedField(entity_type: EntityType) {
+  const queryClient = useQueryClient();
+
+  return useMutation<DerivedField[], unknown, string>({
+    mutationFn: async (key) => {
+      const response = await fetch(`${getAPIURL()}/field/derived/${entity_type}/${key}`, {
+        method: "DELETE",
+      });
+
+      if (!response.ok) {
+        throw new Error((await response.json()).message);
+      }
+
+      return response.json();
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: ["derivedFields", entity_type],
+      });
+    },
+  });
+}
+
+export function usePreviewDerivedField(entity_type: EntityType) {
+  return useMutation<
+    DerivedFieldPreview,
+    unknown,
+    { expression_json: Record<string, unknown>; sample_values: Record<string, unknown> }
+  >({
+    mutationFn: async ({ expression_json, sample_values }) => {
+      const response = await fetch(`${getAPIURL()}/field/derived/${entity_type}/preview`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          expression_json,
+          sample_values,
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error((await response.json()).message);
+      }
+
+      return response.json();
+    },
+  });
+}
diff --git a/scripts/json_logic_parity.py b/scripts/json_logic_parity.py
new file mode 100644
index 000000000..0bad6b07f
--- /dev/null
+++ b/scripts/json_logic_parity.py
@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""Run JSON Logic parity fixtures against a selected Python runtime."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+TIME_RE = re.compile(r"^\d{2}:\d{2}:\d{2}$")
+
+
+@dataclass
+class FixtureResult:
+    fixture_id: str
+    status: str
+    detail: str = ""
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--fixtures",
+        type=Path,
+        default=Path("tests_integration/tests/fields/json_logic_parity_fixtures.json"),
+        help="Path to JSON fixtures file.",
+    )
+    parser.add_argument(
+        "--engine",
+        choices=["json_logic_py"],
+        default="json_logic_py",
+        help="Python evaluator runtime to use.",
+    )
+    return parser.parse_args()
+
+
+def _as_datetime(value: Any) -> datetime:
+    if isinstance(value, datetime):
+        dt = value
+    elif isinstance(value, str):
+        normalized = value.strip()
+        if normalized.endswith("Z"):
+            normalized = f"{normalized[:-1]}+00:00"
+        dt = datetime.fromisoformat(normalized)
+    else:
+        raise ValueError(f"Unsupported datetime input: {value!r}")
+
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def _date_only(value: Any) -> str:
+    return _as_datetime(value).date().isoformat()
+
+
+def _time_only(value: Any) -> str:
+    return _as_datetime(value).time().replace(microsecond=0).isoformat()
+
+
+def _days_between(start: Any, end: Any) -> float:
+    return (_as_datetime(end) - _as_datetime(start)).total_seconds() / 86400
+
+
+def _hours_between(start: Any, end: Any) -> float:
+    return (_as_datetime(end) - _as_datetime(start)).total_seconds() / 3600
+
+
+def _hue_from_hex(value: Any) -> float:
+    if not isinstance(value, str):
+        raise ValueError("hue_from_hex expects a hex color string.")
+
+    normalized = value.strip().lstrip("#")
+    if len(normalized) == 3:
+        normalized = "".join(char * 2 for char in normalized)
+    if len(normalized) != 6:
+        raise ValueError("hue_from_hex expects 3 or 6 hex digits.")
+
+    red = int(normalized[0:2], 16) / 255
+    green = int(normalized[2:4], 16) / 255
+    blue = int(normalized[4:6], 16) / 255
+
+    max_value = max(red, green, blue)
+    min_value = min(red, green, blue)
+    delta = max_value - min_value
+    if delta == 0:
+        return 0.0
+
+    if max_value == red:
+        hue = ((green - blue) / delta) % 6
+    elif max_value == green:
+        hue = (blue - red) / delta + 2
+    else:
+        hue = (red - green) / delta + 4
+
+    return round((hue * 60) % 360, 3)
+
+
+def _coalesce(*values: Any) -> Any:
+    for value in values:
+        if value is not None:
+            return value
+    return None
+
+
+def _replace(value: Any, old: Any, new: Any) -> str:
+    return str(value).replace(str(old), str(new))
+
+
+def _to_number(value: Any) -> float:
+    if isinstance(value, bool):
+        return float(int(value))
+    if isinstance(value, (int, float)):
+        return float(value)
+    return float(str(value))
+
+
+def _install_custom_operations(operations: dict[str, Any]) -> None:
+    # Keep helper/operator names aligned with the planned Formula Extra Fields vocabulary so this
+    # harness reflects the real target behavior instead of raw library defaults.
+    operations.update(
+        {
+            "abs": abs,
+            "round": round,
+            "floor": math.floor,
+            "ceil": math.ceil,
+            "coalesce": _coalesce,
+            "today": lambda: datetime.now(timezone.utc).date().isoformat(),
+            "date_only": _date_only,
+            "time_only": _time_only,
+            "days_between": _days_between,
+            "hours_between": _hours_between,
+            "hue_from_hex": _hue_from_hex,
+            "upper": lambda value: str(value).upper(),
+            "lower": lambda value: str(value).lower(),
+            "trim": lambda value: str(value).strip(),
+            "length": lambda value: len(value),
+            "replace": _replace,
+            "timestamp": lambda value: _as_datetime(value).timestamp(),
+            "to_number": _to_number,
+        },
+    )
+
+
+def _load_engine(engine_name: str) -> Any:
+    if engine_name != "json_logic_py":
+        raise RuntimeError(f"Unsupported engine: {engine_name}")
+
+    try:
+        from json_logic import jsonLogic, operations  # type: ignore[import-not-found]
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            "json-logic-py is not installed. Install candidate runtime first, e.g. "
+            "`pip install json-logic-py`.",
+        ) from exc
+
+    _install_custom_operations(operations)
+    return jsonLogic
+
+
+def _validate_result_type(value: Any, result_type: str) -> None:
+    if result_type == "number":
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ValueError("result_type_mismatch:number")
+        return
+    if result_type == "text":
+        if not isinstance(value, str):
+            raise ValueError("result_type_mismatch:text")
+        return
+    if result_type == "boolean":
+        if not isinstance(value, bool):
+            raise ValueError("result_type_mismatch:boolean")
+        return
+    if result_type == "date":
+        if not isinstance(value, str) or DATE_RE.match(value) is None:
+            raise ValueError("result_type_mismatch:date")
+        return
+    if result_type == "time":
+        if not isinstance(value, str) or TIME_RE.match(value) is None:
+            raise ValueError("result_type_mismatch:time")
+        return
+    if result_type == "datetime":
+        if not isinstance(value, str):
+            raise ValueError("result_type_mismatch:datetime")
+        _as_datetime(value)
+        return
+    raise ValueError(f"Unsupported result type: {result_type}")
+
+
+def _classify_error(exc: Exception) -> str:
+    message = str(exc)
+    if "Unrecognized operation" in message:
+        return "operator_not_allowed"
+    if "result_type_mismatch" in message:
+        return "result_type_mismatch"
+    if any(token in message for token in ["NoneType", "missing", "float()", "unsupported operand"]):
+        return "missing_reference"
+    return "other"
+
+
+def _compare_values(actual: Any, expected: Any) -> bool:
+    if isinstance(actual, (float, int)) and isinstance(expected, (float, int)):
+        return math.isclose(float(actual), float(expected), rel_tol=1e-9, abs_tol=1e-9)
+    return actual == expected
+
+
+def run_fixtures(fixtures_path: Path, engine_name: str) -> list[FixtureResult]:
+    evaluator = _load_engine(engine_name)
+    fixtures = json.loads(fixtures_path.read_text(encoding="utf-8"))
+    results: list[FixtureResult] = []
+
+    for fixture in fixtures:
+        fixture_id = fixture["id"]
+        result_type = fixture["result_type"]
+        expression_json = fixture["expression_json"]
+        scope = fixture.get("scope", {})
+        expected_error = fixture.get("expect_error")
+        expected_value = fixture.get("expected")
+        expected_shape = fixture.get("expected_shape")
+
+        try:
+            actual = evaluator(expression_json, scope)
+            _validate_result_type(actual, result_type)
+            if expected_error:
+                results.append(
+                    FixtureResult(
+                        fixture_id=fixture_id,
+                        status="fail",
+                        detail=f"expected error `{expected_error}` but evaluation succeeded with `{actual!r}`",
+                    ),
+                )
+                continue
+            if expected_shape == "yyyy-mm-dd":
+                if not isinstance(actual, str) or DATE_RE.match(actual) is None:
+                    results.append(
+                        FixtureResult(
+                            fixture_id=fixture_id,
+                            status="fail",
+                            detail=f"expected date shape yyyy-mm-dd but got `{actual!r}`",
+                        ),
+                    )
+                    continue
+            elif expected_value is not None and not _compare_values(actual, expected_value):
+                results.append(
+                    FixtureResult(
+                        fixture_id=fixture_id,
+                        status="fail",
+                        detail=f"expected `{expected_value!r}` but got `{actual!r}`",
+                    ),
+                )
+                continue
+            results.append(FixtureResult(fixture_id=fixture_id, status="pass"))
+        except Exception as exc:  # noqa: BLE001
+            if not expected_error:
+                results.append(FixtureResult(fixture_id=fixture_id, status="fail", detail=f"unexpected error: {exc}"))
+                continue
+            actual_error = _classify_error(exc)
+            if actual_error != expected_error:
+                results.append(
+                    FixtureResult(
+                        fixture_id=fixture_id,
+                        status="fail",
+                        detail=f"expected error `{expected_error}` but got `{actual_error}` ({exc})",
+                    ),
+                )
+                continue
+            results.append(FixtureResult(fixture_id=fixture_id, status="pass"))
+
+    return results
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        results = run_fixtures(args.fixtures, args.engine)
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}")  # noqa: T201
+        return 2
+
+    passed = [result for result in results if result.status == "pass"]
+    failed = [result for result in results if result.status != "pass"]
+
+    print(f"Engine: {args.engine}")  # noqa: T201
+    print(f"Fixtures: {args.fixtures}")  # noqa: T201
+    print(f"Passed: {len(passed)} / {len(results)}")  # noqa: T201
+    if failed:
+        print("Failures:")  # noqa: T201
+        for item in failed:
+            print(f"- {item.fixture_id}: {item.detail}")  # noqa: T201
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/pr-preflight.sh b/scripts/pr-preflight.sh
new file mode 100755
index 000000000..703c7ad8d
--- /dev/null
+++ b/scripts/pr-preflight.sh
@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/pr-preflight.sh <pr> [options]
+
+Examples:
+  scripts/pr-preflight.sh 874 --expected-worktree /private/tmp/spoolman_pr874_runtime_iQoS --expected-branch feat/complex-fields-framework --strict
+  scripts/pr-preflight.sh 874 --expected-worktree /private/tmp/spoolman_pr874_runtime_iQoS --expected-branch feat/complex-fields-framework --strict --require-container --require-url
+  scripts/pr-preflight.sh 876 --expected-branch tmp/pr876-template-filters --strict
+
+Options:
+  --expected-worktree <abs-path>   Exact worktree path required for strict checks.
+  --expected-branch <name>         Exact branch name required for strict checks.
+  --require-container              Require spoolman_pr<PR>_8<PR> to be running.
+  --require-url                    Require localhost:8<PR> to respond with HTTP status.
+  --strict                         Exit non-zero when any mismatch is found.
+EOF
+}
+
+if [[ "${1:-}" == "" || "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if ! [[ "$1" =~ ^[0-9]+$ ]]; then
+  echo "ERROR: first argument must be a numeric PR id." >&2
+  usage
+  exit 1
+fi
+
+PR="$1"
+shift
+
+EXPECTED_WORKTREE=""
+EXPECTED_BRANCH=""
+REQUIRE_CONTAINER=0
+REQUIRE_URL=0
+STRICT=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --expected-worktree)
+      EXPECTED_WORKTREE="${2:-}"
+      shift 2
+      ;;
+    --expected-branch)
+      EXPECTED_BRANCH="${2:-}"
+      shift 2
+      ;;
+    --require-container)
+      REQUIRE_CONTAINER=1
+      shift
+      ;;
+    --require-url)
+      REQUIRE_URL=1
+      shift
+      ;;
+    --strict)
+      STRICT=1
+      shift
+      ;;
+    *)
+      echo "ERROR: unknown option: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if ! git rev-parse --show-toplevel >/dev/null 2>&1; then
+  echo "ERROR: not inside a git repository." >&2
+  exit 1
+fi
+
+CURRENT_PWD="$(pwd -P)"
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+HEAD_LINE="$(git log --oneline -n 1)"
+
+PORT="8${PR}"
+CONTAINER="spoolman_pr${PR}_${PORT}"
+DB_PATH="/tmp/spoolman_pr_${PR}_data"
+URL="http://localhost:${PORT}"
+
+echo "PR            : #${PR}"
+echo "Repo Root     : ${REPO_ROOT}"
+echo "Worktree      : ${CURRENT_PWD}"
+echo "Branch        : ${CURRENT_BRANCH}"
+echo "HEAD          : ${HEAD_LINE}"
+echo "Container     : ${CONTAINER}"
+echo "Port          : ${PORT}"
+echo "DB Mount      : ${DB_PATH}"
+echo "URL           : ${URL}"
+echo "Strict Mode   : ${STRICT}"
+
+ERRORS=0
+WARNINGS=0
+
+if [[ -n "${EXPECTED_WORKTREE}" && "${CURRENT_PWD}" != "${EXPECTED_WORKTREE}" ]]; then
+  echo "MISMATCH: worktree '${CURRENT_PWD}' != expected '${EXPECTED_WORKTREE}'" >&2
+  ERRORS=1
+fi
+
+if [[ -n "${EXPECTED_BRANCH}" && "${CURRENT_BRANCH}" != "${EXPECTED_BRANCH}" ]]; then
+  echo "MISMATCH: branch '${CURRENT_BRANCH}' != expected '${EXPECTED_BRANCH}'" >&2
+  ERRORS=1
+fi
+
+if [[ "${CURRENT_BRANCH}" == "HEAD" ]]; then
+  echo "MISMATCH: detached HEAD detected. Switch to the PR branch before editing." >&2
+  ERRORS=1
+fi
+
+# If no explicit expected values are provided, still surface a context warning when
+# neither path nor branch appears to include the PR id.
+if [[ -z "${EXPECTED_WORKTREE}" && -z "${EXPECTED_BRANCH}" ]]; then
+  if ! [[ "${CURRENT_PWD}" =~ ${PR} || "${CURRENT_BRANCH}" =~ ${PR} ]]; then
+    echo "WARNING: PR id '${PR}' not found in current worktree path or branch name." >&2
+    WARNINGS=1
+  fi
+fi
+
+if command -v docker >/dev/null 2>&1; then
+  echo "Docker        :"
+  CONTAINER_LINE="$(docker ps --format '{{.Names}}\t{{.Status}}\t{{.Ports}}' | awk -v name="${CONTAINER}" '$1 == name {print $0}')"
+  if [[ -n "${CONTAINER_LINE}" ]]; then
+    echo "  ${CONTAINER_LINE}"
+  else
+    echo "  (not running)"
+    if [[ "${REQUIRE_CONTAINER}" -eq 1 ]]; then
+      echo "MISMATCH: required container '${CONTAINER}' is not running." >&2
+      ERRORS=1
+    fi
+  fi
+else
+  echo "Docker        : not found"
+  if [[ "${REQUIRE_CONTAINER}" -eq 1 ]]; then
+    echo "MISMATCH: --require-container specified but docker is not available." >&2
+    ERRORS=1
+  fi
+fi
+
+if [[ "${REQUIRE_URL}" -eq 1 ]]; then
+  if command -v curl >/dev/null 2>&1; then
+    HTTP_CODE="$(curl -sS -o /dev/null -w '%{http_code}' "${URL}" || true)"
+    echo "URL Probe     : ${HTTP_CODE}"
+    if [[ "${HTTP_CODE}" == "000" ]]; then
+      echo "MISMATCH: URL '${URL}' is not reachable." >&2
+      ERRORS=1
+    fi
+  else
+    echo "URL Probe     : curl not found"
+    echo "MISMATCH: --require-url specified but curl is not available." >&2
+    ERRORS=1
+  fi
+fi
+
+if [[ "${ERRORS}" -eq 0 ]]; then
+  if [[ "${WARNINGS}" -eq 0 ]]; then
+    echo "RESULT        : PASS"
+  else
+    echo "RESULT        : PASS (with warnings)"
+  fi
+else
+  echo "RESULT        : FAIL"
+fi
+
+if [[ "${STRICT}" -eq 1 && "${ERRORS}" -ne 0 ]]; then
+  echo "ERROR: strict preflight failed." >&2
+  exit 2
+fi
diff --git a/spoolman/api/v1/field.py b/spoolman/api/v1/field.py
index 36e63d845..929fbb885 100644
--- a/spoolman/api/v1/field.py
+++ b/spoolman/api/v1/field.py
@@ -9,6 +9,16 @@
 
 from spoolman.api.v1.models import Message
 from spoolman.database.database import get_db_session
+from spoolman.derived_fields import (
+    DerivedFieldDefinition,
+    DerivedFieldParameters,
+    DerivedFieldPreviewRequest,
+    DerivedFieldPreviewResponse,
+    add_or_update_derived_field,
+    delete_derived_field,
+    get_derived_fields,
+    preview_derived_payload,
+)
 from spoolman.exceptions import ItemNotFoundError
 from spoolman.extra_fields import (
     EntityType,
@@ -29,6 +39,101 @@
 logger = logging.getLogger(__name__)
 
 
+@router.get(
+    "/derived/{entity_type}",
+    name="Get derived fields",
+    description="Get all user-defined derived fields for a specific entity type.",
+    response_model_exclude_none=True,
+)
+async def get_derived(
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+    entity_type: Annotated[EntityType, Path(description="Entity type this derived field is for")],
+) -> list[DerivedFieldDefinition]:
+    return await get_derived_fields(db, entity_type)
+
+
+@router.post(
+    "/derived/{entity_type}/preview",
+    name="Preview derived field",
+    description="Validate and preview a derived field JSON Logic expression with sample values.",
+    response_model_exclude_none=True,
+    response_model=DerivedFieldPreviewResponse,
+    responses={400: {"model": Message}},
+)
+async def preview_derived(
+    entity_type: Annotated[EntityType, Path(description="Entity type this derived field is for")],
+    body: DerivedFieldPreviewRequest,
+) -> DerivedFieldPreviewResponse | JSONResponse:
+    # The route stays entity-scoped for UI symmetry, but preview validation is intentionally pure:
+    # it only checks expression syntax/helpers against sample values and does not read entity data.
+    del entity_type
+    try:
+        return preview_derived_payload(
+            expression_json=body.expression_json,
+            sample_values=body.sample_values,
+        )
+    except ValueError as exc:
+        return JSONResponse(status_code=400, content=Message(message=str(exc)).dict())
+
+
+@router.post(
+    "/derived/{entity_type}/{key}",
+    name="Add or update derived field",
+    description=(
+        "Add or update a derived field for a specific entity type. "
+        "Returns the full list of derived fields for the entity type."
+    ),
+    response_model_exclude_none=True,
+    response_model=list[DerivedFieldDefinition],
+    responses={400: {"model": Message}},
+)
+async def update_derived(
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+    entity_type: Annotated[EntityType, Path(description="Entity type this derived field is for")],
+    key: Annotated[str, Path(min_length=1, max_length=64, pattern="^[a-z0-9_]+$")],
+    body: DerivedFieldParameters,
+) -> list[DerivedFieldDefinition] | JSONResponse:
+    dict_body = body.model_dump()
+    dict_body["key"] = key
+    dict_body["entity_type"] = entity_type
+    body_with_key = DerivedFieldDefinition.model_validate(dict_body)
+
+    try:
+        await add_or_update_derived_field(db, entity_type, body_with_key)
+    except ValueError as exc:
+        return JSONResponse(status_code=400, content=Message(message=str(exc)).dict())
+
+    return await get_derived_fields(db, entity_type)
+
+
+@router.delete(
+    "/derived/{entity_type}/{key}",
+    name="Delete derived field",
+    description=(
+        "Delete a derived field for a specific entity type. Returns the full list of derived fields for the entity type."
+    ),
+    response_model_exclude_none=True,
+    response_model=list[DerivedFieldDefinition],
+    responses={404: {"model": Message}},
+)
+async def delete_derived(
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+    entity_type: Annotated[EntityType, Path(description="Entity type this derived field is for")],
+    key: Annotated[str, Path(min_length=1, max_length=64, pattern="^[a-z0-9_]+$")],
+) -> list[DerivedFieldDefinition] | JSONResponse:
+    try:
+        await delete_derived_field(db, entity_type, key)
+    except ItemNotFoundError:
+        return JSONResponse(
+            status_code=404,
+            content=Message(
+                message=f"Derived field with key {key} does not exist for entity type {entity_type.name}",
+            ).dict(),
+        )
+
+    return await get_derived_fields(db, entity_type)
+
+
 @router.get(
     "/{entity_type}",
     name="Get extra fields",
diff --git a/spoolman/api/v1/filament.py b/spoolman/api/v1/filament.py
index 3e3f859af..1b595a20b 100644
--- a/spoolman/api/v1/filament.py
+++ b/spoolman/api/v1/filament.py
@@ -14,6 +14,12 @@
 from spoolman.database import filament
 from spoolman.database.database import get_db_session
 from spoolman.database.utils import SortOrder
+from spoolman.derived_fields import (
+    build_formula_scope,
+    evaluate_derived_fields_for_scope,
+    get_derived_fields_for_surface,
+    resolve_include_derived_in_api,
+)
 from spoolman.exceptions import ItemDeleteError
 from spoolman.extra_fields import EntityType, get_extra_fields, validate_extra_field_dict
 from spoolman.ws import websocket_manager
@@ -318,6 +324,16 @@ async def find(
         int | None,
         Query(title="Limit", description="Maximum number of items in the response."),
     ] = None,
+    include_derived: Annotated[
+        bool | None,
+        Query(
+            title="Include Derived",
+            description=(
+                "Include formula extra fields under payload.derived. "
+                "If omitted, the api_include_derived_fields setting is used."
+            ),
+        ),
+    ] = None,
     offset: Annotated[int, Query(title="Offset", description="Offset in the full result set if a limit is set.")] = 0,
 ) -> JSONResponse:
     sort_by: dict[str, SortOrder] = {}
@@ -355,11 +371,32 @@ async def find(
         limit=limit,
         offset=offset,
     )
+    include_derived_resolved = await resolve_include_derived_in_api(db, include_derived)
+    payload: list[Filament] = []
+    # List endpoints should only evaluate fields configured for list/table surfaces.
+    derived_fields = (
+        await get_derived_fields_for_surface(db, EntityType.filament, "list", api_enabled_only=True)
+        if include_derived_resolved
+        else []
+    )
+
+    for db_item in db_items:
+        filament_payload = Filament.from_db(db_item)
+        if include_derived_resolved and derived_fields:
+            scope = build_formula_scope(filament_payload.model_dump(exclude_none=True))
+            derived_values = evaluate_derived_fields_for_scope(
+                derived_fields=derived_fields,
+                scope=scope,
+                entity_type=EntityType.filament,
+                entity_id=filament_payload.id,
+            )
+            filament_payload = filament_payload.model_copy(update={"derived": derived_values or None})
+        payload.append(filament_payload)
 
     # Set x-total-count header for pagination
     return JSONResponse(
         content=jsonable_encoder(
-            (Filament.from_db(db_item) for db_item in db_items),
+            payload,
             exclude_none=True,
         ),
         headers={"x-total-count": str(total_count)},
@@ -397,9 +434,38 @@ async def notify_any(
 async def get(
     db: Annotated[AsyncSession, Depends(get_db_session)],
     filament_id: int,
+    include_derived: Annotated[
+        bool | None,
+        Query(
+            title="Include Derived",
+            description=(
+                "Include formula extra fields under payload.derived. "
+                "If omitted, the api_include_derived_fields setting is used."
+            ),
+        ),
+    ] = None,
 ) -> Filament:
     db_item = await filament.get_by_id(db, filament_id)
-    return Filament.from_db(db_item)
+    filament_payload = Filament.from_db(db_item)
+    include_derived_resolved = await resolve_include_derived_in_api(db, include_derived)
+    if include_derived_resolved:
+        # Detail endpoints should evaluate show-surface formulas only.
+        derived_fields = await get_derived_fields_for_surface(
+            db,
+            EntityType.filament,
+            "show",
+            api_enabled_only=True,
+        )
+        if derived_fields:
+            scope = build_formula_scope(filament_payload.model_dump(exclude_none=True))
+            derived_values = evaluate_derived_fields_for_scope(
+                derived_fields=derived_fields,
+                scope=scope,
+                entity_type=EntityType.filament,
+                entity_id=filament_payload.id,
+            )
+            filament_payload = filament_payload.model_copy(update={"derived": derived_values or None})
+    return filament_payload
 
 
 @router.websocket(
diff --git a/spoolman/api/v1/models.py b/spoolman/api/v1/models.py
index a24d79f7c..9dba64f42 100644
--- a/spoolman/api/v1/models.py
+++ b/spoolman/api/v1/models.py
@@ -2,7 +2,7 @@
 
 from datetime import datetime, timezone
 from enum import Enum
-from typing import Annotated, Literal
+from typing import Any, Annotated, Literal
 
 from pydantic import BaseModel, Field, PlainSerializer
 
@@ -78,9 +78,13 @@ class Vendor(BaseModel):
             "Query the /fields endpoint for more details about the fields."
         ),
     )
+    derived: dict[str, Any] | None = Field(
+        default=None,
+        description="Optional derived values computed from formula extra fields.",
+    )
 
     @staticmethod
-    def from_db(item: models.Vendor) -> "Vendor":
+    def from_db(item: models.Vendor, derived: dict[str, Any] | None = None) -> "Vendor":
         """Create a new Pydantic vendor object from a database vendor object."""
         return Vendor(
             id=item.id,
@@ -90,6 +94,7 @@ def from_db(item: models.Vendor) -> "Vendor":
             empty_spool_weight=item.empty_spool_weight,
             external_id=item.external_id,
             extra={field.key: field.value for field in item.extra},
+            derived=derived,
         )
 
 
@@ -197,9 +202,13 @@ class Filament(BaseModel):
             "Query the /fields endpoint for more details about the fields."
         ),
     )
+    derived: dict[str, Any] | None = Field(
+        default=None,
+        description="Optional derived values computed from formula extra fields.",
+    )
 
     @staticmethod
-    def from_db(item: models.Filament) -> "Filament":
+    def from_db(item: models.Filament, derived: dict[str, Any] | None = None) -> "Filament":
         """Create a new Pydantic filament object from a database filament object."""
         return Filament(
             id=item.id,
@@ -223,6 +232,7 @@ def from_db(item: models.Filament) -> "Filament":
             ),
             external_id=item.external_id,
             extra={field.key: field.value for field in item.extra},
+            derived=derived,
         )
 
 
@@ -309,9 +319,13 @@ class Spool(BaseModel):
             "Query the /fields endpoint for more details about the fields."
         ),
     )
+    derived: dict[str, Any] | None = Field(
+        default=None,
+        description="Optional derived values computed from formula extra fields.",
+    )
 
     @staticmethod
-    def from_db(item: models.Spool) -> "Spool":
+    def from_db(item: models.Spool, derived: dict[str, Any] | None = None) -> "Spool":
         """Create a new Pydantic spool object from a database spool object."""
         filament = Filament.from_db(item.filament)
 
@@ -357,6 +371,7 @@ def from_db(item: models.Spool) -> "Spool":
             comment=item.comment,
             archived=item.archived if item.archived is not None else False,
             extra={field.key: field.value for field in item.extra},
+            derived=derived,
         )
 
 
diff --git a/spoolman/api/v1/spool.py b/spoolman/api/v1/spool.py
index 8f667e3da..5f17224a2 100644
--- a/spoolman/api/v1/spool.py
+++ b/spoolman/api/v1/spool.py
@@ -15,6 +15,12 @@
 from spoolman.database import spool
 from spoolman.database.database import get_db_session
 from spoolman.database.utils import SortOrder
+from spoolman.derived_fields import (
+    build_formula_scope,
+    evaluate_derived_fields_for_scope,
+    get_derived_fields_for_surface,
+    resolve_include_derived_in_api,
+)
 from spoolman.exceptions import ItemCreateError, SpoolMeasureError
 from spoolman.extra_fields import EntityType, get_extra_fields, validate_extra_field_dict
 from spoolman.ws import websocket_manager
@@ -265,6 +271,16 @@ async def find(
         int | None,
         Query(title="Limit", description="Maximum number of items in the response."),
     ] = None,
+    include_derived: Annotated[
+        bool | None,
+        Query(
+            title="Include Derived",
+            description=(
+                "Include formula extra fields under payload.derived. "
+                "If omitted, the api_include_derived_fields setting is used."
+            ),
+        ),
+    ] = None,
     offset: Annotated[int, Query(title="Offset", description="Offset in the full result set if a limit is set.")] = 0,
 ) -> JSONResponse:
     sort_by: dict[str, SortOrder] = {}
@@ -299,11 +315,32 @@ async def find(
         limit=limit,
         offset=offset,
     )
+    include_derived_resolved = await resolve_include_derived_in_api(db, include_derived)
+    payload: list[Spool] = []
+    # List endpoints should only evaluate fields configured for list/table surfaces.
+    derived_fields = (
+        await get_derived_fields_for_surface(db, EntityType.spool, "list", api_enabled_only=True)
+        if include_derived_resolved
+        else []
+    )
+
+    for db_item in db_items:
+        spool_payload = Spool.from_db(db_item)
+        if include_derived_resolved and derived_fields:
+            scope = build_formula_scope(spool_payload.model_dump(exclude_none=True))
+            derived_values = evaluate_derived_fields_for_scope(
+                derived_fields=derived_fields,
+                scope=scope,
+                entity_type=EntityType.spool,
+                entity_id=spool_payload.id,
+            )
+            spool_payload = spool_payload.model_copy(update={"derived": derived_values or None})
+        payload.append(spool_payload)
 
     # Set x-total-count header for pagination
     return JSONResponse(
         content=jsonable_encoder(
-            (Spool.from_db(db_item) for db_item in db_items),
+            payload,
             exclude_none=True,
         ),
         headers={"x-total-count": str(total_count)},
@@ -341,9 +378,33 @@ async def notify_any(
 async def get(
     db: Annotated[AsyncSession, Depends(get_db_session)],
     spool_id: int,
+    include_derived: Annotated[
+        bool | None,
+        Query(
+            title="Include Derived",
+            description=(
+                "Include formula extra fields under payload.derived. "
+                "If omitted, the api_include_derived_fields setting is used."
+            ),
+        ),
+    ] = None,
 ) -> Spool:
     db_item = await spool.get_by_id(db, spool_id)
-    return Spool.from_db(db_item)
+    spool_payload = Spool.from_db(db_item)
+    include_derived_resolved = await resolve_include_derived_in_api(db, include_derived)
+    if include_derived_resolved:
+        # Detail endpoints should evaluate show-surface formulas only.
+        derived_fields = await get_derived_fields_for_surface(db, EntityType.spool, "show", api_enabled_only=True)
+        if derived_fields:
+            scope = build_formula_scope(spool_payload.model_dump(exclude_none=True))
+            derived_values = evaluate_derived_fields_for_scope(
+                derived_fields=derived_fields,
+                scope=scope,
+                entity_type=EntityType.spool,
+                entity_id=spool_payload.id,
+            )
+            spool_payload = spool_payload.model_copy(update={"derived": derived_values or None})
+    return spool_payload
 
 
 @router.websocket(
diff --git a/spoolman/api/v1/vendor.py b/spoolman/api/v1/vendor.py
index 9216fba30..cbc4ab363 100644
--- a/spoolman/api/v1/vendor.py
+++ b/spoolman/api/v1/vendor.py
@@ -13,6 +13,12 @@
 from spoolman.database import vendor
 from spoolman.database.database import get_db_session
 from spoolman.database.utils import SortOrder
+from spoolman.derived_fields import (
+    build_formula_scope,
+    evaluate_derived_fields_for_scope,
+    get_derived_fields_for_surface,
+    resolve_include_derived_in_api,
+)
 from spoolman.extra_fields import EntityType, get_extra_fields, validate_extra_field_dict
 from spoolman.ws import websocket_manager
 
@@ -116,6 +122,16 @@ async def find(
         int | None,
         Query(title="Limit", description="Maximum number of items in the response."),
     ] = None,
+    include_derived: Annotated[
+        bool | None,
+        Query(
+            title="Include Derived",
+            description=(
+                "Include formula extra fields under payload.derived. "
+                "If omitted, the api_include_derived_fields setting is used."
+            ),
+        ),
+    ] = None,
     offset: Annotated[int, Query(title="Offset", description="Offset in the full result set if a limit is set.")] = 0,
 ) -> JSONResponse:
     sort_by: dict[str, SortOrder] = {}
@@ -132,10 +148,31 @@ async def find(
         limit=limit,
         offset=offset,
     )
+    include_derived_resolved = await resolve_include_derived_in_api(db, include_derived)
+    payload: list[Vendor] = []
+    # List endpoints should only evaluate fields configured for list/table surfaces.
+    derived_fields = (
+        await get_derived_fields_for_surface(db, EntityType.vendor, "list", api_enabled_only=True)
+        if include_derived_resolved
+        else []
+    )
+
+    for db_item in db_items:
+        vendor_payload = Vendor.from_db(db_item)
+        if include_derived_resolved and derived_fields:
+            scope = build_formula_scope(vendor_payload.model_dump(exclude_none=True))
+            derived_values = evaluate_derived_fields_for_scope(
+                derived_fields=derived_fields,
+                scope=scope,
+                entity_type=EntityType.vendor,
+                entity_id=vendor_payload.id,
+            )
+            vendor_payload = vendor_payload.model_copy(update={"derived": derived_values or None})
+        payload.append(vendor_payload)
     # Set x-total-count header for pagination
     return JSONResponse(
         content=jsonable_encoder(
-            (Vendor.from_db(db_item) for db_item in db_items),
+            payload,
             exclude_none=True,
         ),
         headers={"x-total-count": str(total_count)},
@@ -173,9 +210,33 @@ async def notify_any(
 async def get(
     db: Annotated[AsyncSession, Depends(get_db_session)],
     vendor_id: int,
+    include_derived: Annotated[
+        bool | None,
+        Query(
+            title="Include Derived",
+            description=(
+                "Include formula extra fields under payload.derived. "
+                "If omitted, the api_include_derived_fields setting is used."
+            ),
+        ),
+    ] = None,
 ) -> Vendor:
     db_item = await vendor.get_by_id(db, vendor_id)
-    return Vendor.from_db(db_item)
+    vendor_payload = Vendor.from_db(db_item)
+    include_derived_resolved = await resolve_include_derived_in_api(db, include_derived)
+    if include_derived_resolved:
+        # Detail endpoints should evaluate show-surface formulas only.
+        derived_fields = await get_derived_fields_for_surface(db, EntityType.vendor, "show", api_enabled_only=True)
+        if derived_fields:
+            scope = build_formula_scope(vendor_payload.model_dump(exclude_none=True))
+            derived_values = evaluate_derived_fields_for_scope(
+                derived_fields=derived_fields,
+                scope=scope,
+                entity_type=EntityType.vendor,
+                entity_id=vendor_payload.id,
+            )
+            vendor_payload = vendor_payload.model_copy(update={"derived": derived_values or None})
+    return vendor_payload
 
 
 @router.websocket(
diff --git a/spoolman/derived_fields.py b/spoolman/derived_fields.py
new file mode 100644
index 000000000..419224c9e
--- /dev/null
+++ b/spoolman/derived_fields.py
@@ -0,0 +1,613 @@
+"""User-defined derived fields with safe expression evaluation."""
+
+import colorsys
+import json
+import logging
+import math
+from datetime import date, datetime, time, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, ValidationError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from spoolman.database import setting as db_setting
+from spoolman.exceptions import ItemNotFoundError
+from spoolman.extra_fields import EntityType
+from spoolman.settings import parse_setting
+
+logger = logging.getLogger(__name__)
+
+class DerivedFieldType(Enum):
+    """Supported output types for a derived field."""
+
+    number = "number"
+    text = "text"
+
+
+class DerivedFieldDefinition(BaseModel):
+    """Stored user-defined derived field."""
+
+    key: str = Field(description="Unique key", pattern="^[a-z0-9_]+$", min_length=1, max_length=64)
+    entity_type: EntityType = Field(description="Entity type this derived field is for")
+    name: str = Field(description="Display name", min_length=1, max_length=128)
+    description: str | None = Field(default=None, description="Optional description", max_length=512)
+    result_type: DerivedFieldType = Field(description="Expected result type")
+    expression_json: dict[str, Any] = Field(description="Derived expression in JSON Logic format")
+    surfaces: list[str] = Field(default_factory=list, description="Where this derived field should appear")
+    allow_list_column_toggle: bool = Field(
+        default=False,
+        description="Whether list-surface fields can be hidden or shown from the column picker",
+    )
+    include_in_api: bool = Field(
+        default=False,
+        description="Whether this formula field can be exposed in API derived payloads",
+    )
+
+
+class DerivedFieldParameters(BaseModel):
+    """Editable parameters for a derived field."""
+
+    name: str = Field(description="Display name", min_length=1, max_length=128)
+    description: str | None = Field(default=None, description="Optional description", max_length=512)
+    result_type: DerivedFieldType = Field(description="Expected result type")
+    expression_json: dict[str, Any] = Field(description="Derived expression in JSON Logic format")
+    surfaces: list[str] = Field(default_factory=list, description="Where this derived field should appear")
+    allow_list_column_toggle: bool = Field(
+        default=False,
+        description="Whether list-surface fields can be hidden or shown from the column picker",
+    )
+    include_in_api: bool = Field(
+        default=False,
+        description="Whether this formula field can be exposed in API derived payloads",
+    )
+
+
+class DerivedFieldPreviewRequest(BaseModel):
+    """Preview request for evaluating a derived field expression."""
+
+    expression_json: dict[str, Any] = Field(description="Derived expression in JSON Logic format")
+    sample_values: dict[str, Any] = Field(default_factory=dict, description="Sample values keyed by field reference")
+
+
+class DerivedFieldPreviewResponse(BaseModel):
+    """Preview result for a derived field expression."""
+
+    result: str | float | int | bool | None = Field(description="Preview result")
+    references: list[str] = Field(default_factory=list, description="Field references used by the expression")
+
+
+_derived_field_cache: dict[EntityType, list[DerivedFieldDefinition]] = {}
+
+
+def _as_datetime(value: Any) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, date):
+        return datetime.combine(value, time.min)
+    if isinstance(value, str):
+        normalized = value.strip()
+        if normalized.endswith("Z"):
+            normalized = f"{normalized[:-1]}+00:00"
+        return datetime.fromisoformat(normalized)
+    raise ValueError(f"Value {value!r} is not a datetime-compatible input.")
+
+
+def _coalesce(*values: Any) -> Any:
+    for value in values:
+        if value is not None:
+            return value
+    return None
+
+
+def _date_only(value: Any) -> str:
+    return _as_datetime(value).date().isoformat()
+
+
+def _time_only(value: Any) -> str:
+    return _as_datetime(value).timetz().isoformat()
+
+
+def _days_between(start: Any, end: Any) -> float:
+    return (_as_datetime(end) - _as_datetime(start)).total_seconds() / 86400
+
+
+def _hours_between(start: Any, end: Any) -> float:
+    return (_as_datetime(end) - _as_datetime(start)).total_seconds() / 3600
+
+
+def _hue_from_hex(value: Any) -> float:
+    if not isinstance(value, str):
+        raise ValueError("hue_from_hex expects a color string.")
+    normalized = value.strip().lstrip("#")
+    if len(normalized) == 3:
+        normalized = "".join(char * 2 for char in normalized)
+    if len(normalized) != 6:
+        raise ValueError("hue_from_hex expects a 3 or 6 digit hex color.")
+    red = int(normalized[0:2], 16) / 255
+    green = int(normalized[2:4], 16) / 255
+    blue = int(normalized[4:6], 16) / 255
+    hue, _, _ = colorsys.rgb_to_hsv(red, green, blue)
+    return round(hue * 360, 3)
+
+
+def _today() -> str:
+    return datetime.now(timezone.utc).date().isoformat()
+
+
+def _left(value: Any, count: Any = 1) -> str:
+    text = str(value if value is not None else "")
+    try:
+        length = max(0, math.floor(float(count)))
+    except (TypeError, ValueError):
+        length = 1
+    return text[:length]
+
+
+def _right(value: Any, count: Any = 1) -> str:
+    text = str(value if value is not None else "")
+    try:
+        length = max(0, math.floor(float(count)))
+    except (TypeError, ValueError):
+        length = 1
+    if length == 0:
+        return ""
+    return text[-length:]
+
+
+JSON_LOGIC_ALLOWED_OPERATORS = {
+    "var",
+    "if",
+    "and",
+    "or",
+    "!",
+    "==",
+    "!=",
+    "<",
+    "<=",
+    ">",
+    ">=",
+    "+",
+    "-",
+    "*",
+    "/",
+    "%",
+    "min",
+    "max",
+    "round",
+    "floor",
+    "ceil",
+    "abs",
+    "cat",
+    "upper",
+    "lower",
+    "trim",
+    "length",
+    "replace",
+    "left",
+    "right",
+    "coalesce",
+    "today",
+    "year",
+    "month",
+    "day",
+    "hour",
+    "minute",
+    "second",
+    "timestamp",
+    "date_only",
+    "time_only",
+    "days_between",
+    "hours_between",
+    "hue_from_hex",
+}
+
+
+def _normalize_json_logic_args(raw_value: Any) -> list[Any]:
+    if isinstance(raw_value, list):
+        return raw_value
+    return [raw_value]
+
+
+def _normalize_preview_result(value: Any) -> str | float | int | bool | None:
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, (str, float, int, bool)) or value is None:
+        return value
+    return str(value)
+
+
+def _truthy(value: Any) -> bool:
+    return bool(value)
+
+
+def _lookup_reference(reference: Any, scope: dict[str, Any], default: Any = None) -> Any:
+    if isinstance(reference, int):
+        return scope.get(str(reference), default)
+    if not isinstance(reference, str):
+        raise ValueError("JSON Logic var reference must be a string or integer.")
+    if reference == "":
+        return scope
+
+    current: Any = scope
+    for part in reference.split("."):
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+            continue
+        return default
+    return current
+
+
+def _validate_json_logic_node(node: Any, references: set[str]) -> None:
+    if isinstance(node, (str, int, float, bool)) or node is None:
+        return
+    if isinstance(node, list):
+        for value in node:
+            _validate_json_logic_node(value, references)
+        return
+    if not isinstance(node, dict):
+        raise ValueError("JSON Logic expression contains unsupported value types.")
+    if len(node) != 1:
+        raise ValueError("JSON Logic expression objects must contain exactly one operator.")
+
+    operator, raw_args = next(iter(node.items()))
+    if operator not in JSON_LOGIC_ALLOWED_OPERATORS:
+        raise ValueError(f"JSON Logic operator '{operator}' is not allowed.")
+
+    args = _normalize_json_logic_args(raw_args)
+    if operator == "var":
+        if len(args) == 0:
+            raise ValueError("JSON Logic var operator requires at least one argument.")
+        reference = args[0]
+        if not isinstance(reference, (str, int)):
+            raise ValueError("JSON Logic var reference must be a string or integer.")
+        if isinstance(reference, str) and reference != "":
+            references.add(reference)
+        if len(args) > 1:
+            _validate_json_logic_node(args[1], references)
+        return
+
+    for arg in args:
+        _validate_json_logic_node(arg, references)
+
+
+def validate_derived_expression_json(expression_json: dict[str, Any]) -> list[str]:
+    references: set[str] = set()
+    _validate_json_logic_node(expression_json, references)
+    return sorted(references)
+
+
+def _evaluate_json_logic(node: Any, scope: dict[str, Any]) -> Any:
+    if isinstance(node, (str, int, float, bool)) or node is None:
+        return node
+    if isinstance(node, list):
+        return [_evaluate_json_logic(value, scope) for value in node]
+    if not isinstance(node, dict) or len(node) != 1:
+        raise ValueError("JSON Logic expression uses an invalid object shape.")
+
+    operator, raw_args = next(iter(node.items()))
+    args = _normalize_json_logic_args(raw_args)
+
+    if operator == "var":
+        reference = args[0] if len(args) > 0 else ""
+        default = _evaluate_json_logic(args[1], scope) if len(args) > 1 else None
+        return _lookup_reference(reference, scope, default)
+    if operator == "if":
+        if len(args) < 2:
+            raise ValueError("JSON Logic if operator requires at least 2 arguments.")
+        for index in range(0, len(args) - 1, 2):
+            if _truthy(_evaluate_json_logic(args[index], scope)):
+                return _evaluate_json_logic(args[index + 1], scope)
+        if len(args) % 2 == 1:
+            return _evaluate_json_logic(args[-1], scope)
+        return None
+    if operator == "and":
+        result: Any = True
+        for arg in args:
+            result = _evaluate_json_logic(arg, scope)
+            if not _truthy(result):
+                return result
+        return result
+    if operator == "or":
+        result: Any = False
+        for arg in args:
+            result = _evaluate_json_logic(arg, scope)
+            if _truthy(result):
+                return result
+        return result
+    if operator == "!":
+        if len(args) != 1:
+            raise ValueError("JSON Logic ! operator requires one argument.")
+        return not _truthy(_evaluate_json_logic(args[0], scope))
+
+    evaluated_args = [_evaluate_json_logic(arg, scope) for arg in args]
+
+    if operator == "==":
+        return evaluated_args[0] == evaluated_args[1]
+    if operator == "!=":
+        return evaluated_args[0] != evaluated_args[1]
+    if operator == "<":
+        return evaluated_args[0] < evaluated_args[1]
+    if operator == "<=":
+        return evaluated_args[0] <= evaluated_args[1]
+    if operator == ">":
+        return evaluated_args[0] > evaluated_args[1]
+    if operator == ">=":
+        return evaluated_args[0] >= evaluated_args[1]
+    if operator == "+":
+        return sum(evaluated_args)
+    if operator == "-":
+        if len(evaluated_args) == 1:
+            return -evaluated_args[0]
+        return evaluated_args[0] - evaluated_args[1]
+    if operator == "*":
+        result = 1
+        for value in evaluated_args:
+            result *= value
+        return result
+    if operator == "/":
+        if len(evaluated_args) != 2:
+            raise ValueError("JSON Logic / operator requires two arguments.")
+        return evaluated_args[0] / evaluated_args[1]
+    if operator == "%":
+        return evaluated_args[0] % evaluated_args[1]
+    if operator == "min":
+        return min(evaluated_args)
+    if operator == "max":
+        return max(evaluated_args)
+    if operator == "round":
+        return round(evaluated_args[0])
+    if operator == "floor":
+        return math.floor(evaluated_args[0])
+    if operator == "ceil":
+        return math.ceil(evaluated_args[0])
+    if operator == "abs":
+        return abs(evaluated_args[0])
+    if operator == "cat":
+        return "".join(str(value) for value in evaluated_args)
+    if operator == "upper":
+        return str(evaluated_args[0]).upper()
+    if operator == "lower":
+        return str(evaluated_args[0]).lower()
+    if operator == "trim":
+        return str(evaluated_args[0]).strip()
+    if operator == "length":
+        return len(evaluated_args[0])
+    if operator == "replace":
+        return str(evaluated_args[0]).replace(str(evaluated_args[1]), str(evaluated_args[2]))
+    if operator == "left":
+        return _left(evaluated_args[0], evaluated_args[1] if len(evaluated_args) > 1 else 1)
+    if operator == "right":
+        return _right(evaluated_args[0], evaluated_args[1] if len(evaluated_args) > 1 else 1)
+    if operator == "coalesce":
+        return _coalesce(*evaluated_args)
+    if operator == "today":
+        return _today()
+    if operator == "year":
+        return _as_datetime(evaluated_args[0]).year
+    if operator == "month":
+        return _as_datetime(evaluated_args[0]).month
+    if operator == "day":
+        return _as_datetime(evaluated_args[0]).day
+    if operator == "hour":
+        return _as_datetime(evaluated_args[0]).hour
+    if operator == "minute":
+        return _as_datetime(evaluated_args[0]).minute
+    if operator == "second":
+        return _as_datetime(evaluated_args[0]).second
+    if operator == "timestamp":
+        return _as_datetime(evaluated_args[0]).timestamp()
+    if operator == "date_only":
+        return _date_only(evaluated_args[0])
+    if operator == "time_only":
+        return _time_only(evaluated_args[0])
+    if operator == "days_between":
+        return _days_between(evaluated_args[0], evaluated_args[1])
+    if operator == "hours_between":
+        return _hours_between(evaluated_args[0], evaluated_args[1])
+    if operator == "hue_from_hex":
+        return _hue_from_hex(evaluated_args[0])
+
+    raise ValueError(f"JSON Logic operator '{operator}' is not implemented.")
+
+
+def preview_derived_expression_json(
+    expression_json: dict[str, Any],
+    sample_values: dict[str, Any],
+) -> DerivedFieldPreviewResponse:
+    references = validate_derived_expression_json(expression_json)
+    try:
+        result = _evaluate_json_logic(expression_json, sample_values)
+    except Exception as exc:
+        raise ValueError(str(exc)) from exc
+    return DerivedFieldPreviewResponse(result=_normalize_preview_result(result), references=references)
+
+
+def preview_derived_payload(
+    *,
+    expression_json: dict[str, Any],
+    sample_values: dict[str, Any],
+) -> DerivedFieldPreviewResponse:
+    return preview_derived_expression_json(expression_json, sample_values)
+
+
+def _validate_expression_payload(expression_json: dict[str, Any]) -> None:
+    validate_derived_expression_json(expression_json)
+
+
+def _parse_extra_field_value(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        return value
+
+
+def _normalize_formula_scope(value: Any) -> Any:
+    if isinstance(value, dict):
+        normalized: dict[str, Any] = {}
+        for key, nested in value.items():
+            if key == "extra" and isinstance(nested, dict):
+                normalized[key] = {
+                    extra_key: _parse_extra_field_value(extra_value)
+                    for extra_key, extra_value in nested.items()
+                }
+                continue
+            normalized[key] = _normalize_formula_scope(nested)
+        return normalized
+    if isinstance(value, list):
+        return [_normalize_formula_scope(item) for item in value]
+    return value
+
+
+def build_formula_scope(payload: dict[str, Any]) -> dict[str, Any]:
+    """Normalize API payload values into a formula-evaluation scope."""
+    normalized = _normalize_formula_scope(payload)
+    return normalized if isinstance(normalized, dict) else {}
+
+
+def evaluate_derived_fields_for_scope(
+    *,
+    derived_fields: list[DerivedFieldDefinition],
+    scope: dict[str, Any],
+    entity_type: EntityType,
+    entity_id: int | None = None,
+) -> dict[str, Any]:
+    """Evaluate a set of derived fields for one entity payload scope."""
+    values: dict[str, Any] = {}
+    for field in derived_fields:
+        try:
+            result = _evaluate_json_logic(field.expression_json, scope)
+            values[field.key] = _normalize_preview_result(result)
+        except Exception as exc:
+            # Derived output is best-effort in API payloads so one invalid definition never blocks
+            # the base entity response for clients.
+            logger.warning(
+                "Failed to evaluate derived field %s for %s id=%s: %s",
+                field.key,
+                entity_type.name,
+                entity_id,
+                exc,
+            )
+    return values
+
+
+async def get_derived_fields(db: AsyncSession, entity_type: EntityType) -> list[DerivedFieldDefinition]:
+    """Return stored derived fields for an entity type."""
+    if entity_type in _derived_field_cache:
+        return list(_derived_field_cache[entity_type])
+
+    setting_def = parse_setting(f"derived_fields_{entity_type.name}")
+    try:
+        setting = await db_setting.get(db, setting_def)
+        setting_value = setting.value
+    except ItemNotFoundError:
+        setting_value = setting_def.default
+
+    parsed = json.loads(setting_value)
+    if not isinstance(parsed, list):
+        logger.warning("Setting %s is not a list, using default.", setting_def.key)
+        parsed = []
+
+    derived_fields: list[DerivedFieldDefinition] = []
+    for raw_value in parsed:
+        if not isinstance(raw_value, dict):
+            continue
+        try:
+            derived_fields.append(DerivedFieldDefinition.model_validate(raw_value))
+        except ValidationError as exc:
+            logger.warning(
+                "Skipping invalid derived field for %s (key=%s): %s",
+                entity_type.name,
+                raw_value.get("key"),
+                exc,
+            )
+
+    # Return a stable presentation order so settings tables and template variable lists do not
+    # re-shuffle unexpectedly when the stored JSON order changes.
+    derived_fields.sort(key=lambda item: (item.name.lower(), item.key))
+    _derived_field_cache[entity_type] = derived_fields
+    return list(derived_fields)
+
+
+async def get_derived_fields_for_surface(
+    db: AsyncSession,
+    entity_type: EntityType,
+    surface: str | None,
+    *,
+    api_enabled_only: bool = False,
+) -> list[DerivedFieldDefinition]:
+    """Get derived fields filtered by surface, preserving the cached stable order."""
+    derived_fields = await get_derived_fields(db, entity_type)
+    if surface is None:
+        filtered_fields = derived_fields
+    else:
+        filtered_fields = [field for field in derived_fields if surface in field.surfaces]
+
+    if api_enabled_only:
+        # API exposure is a field-level opt-in, so formula definitions can remain available in UI
+        # surfaces without automatically becoming API output.
+        return [field for field in filtered_fields if field.include_in_api]
+    return filtered_fields
+
+
+async def resolve_include_derived_in_api(db: AsyncSession, include_derived: bool | None) -> bool:
+    """Resolve per-request include_derived with a settings-level default."""
+    if include_derived is not None:
+        return include_derived
+
+    setting_def = parse_setting("api_include_derived_fields")
+    default_value = json.loads(setting_def.default)
+    try:
+        setting = await db_setting.get(db, setting_def)
+    except ItemNotFoundError:
+        return default_value
+
+    try:
+        parsed = json.loads(setting.value)
+    except json.JSONDecodeError:
+        logger.warning("Setting %s is not valid JSON, using default.", setting_def.key)
+        return default_value
+
+    if isinstance(parsed, bool):
+        return parsed
+
+    logger.warning("Setting %s is not a boolean, using default.", setting_def.key)
+    return default_value
+
+
+async def add_or_update_derived_field(db: AsyncSession, entity_type: EntityType, derived_field: DerivedFieldDefinition) -> None:
+    """Create or update a derived field."""
+    _validate_expression_payload(derived_field.expression_json)
+
+    existing = await get_derived_fields(db, entity_type)
+    next_fields = [field for field in existing if field.key != derived_field.key]
+    next_fields.append(derived_field)
+    next_fields.sort(key=lambda item: (item.name.lower(), item.key))
+
+    setting_def = parse_setting(f"derived_fields_{entity_type.name}")
+    await db_setting.update(
+        db=db,
+        definition=setting_def,
+        value=json.dumps([field.model_dump(mode="json") for field in next_fields]),
+    )
+    _derived_field_cache[entity_type] = next_fields
+
+
+async def delete_derived_field(db: AsyncSession, entity_type: EntityType, key: str) -> None:
+    """Delete a derived field."""
+    existing = await get_derived_fields(db, entity_type)
+    next_fields = [field for field in existing if field.key != key]
+    if len(next_fields) == len(existing):
+        raise ItemNotFoundError(f"Derived field with key {key} does not exist.")
+
+    setting_def = parse_setting(f"derived_fields_{entity_type.name}")
+    await db_setting.update(
+        db=db,
+        definition=setting_def,
+        value=json.dumps([field.model_dump(mode="json") for field in next_fields]),
+    )
+    _derived_field_cache[entity_type] = next_fields
diff --git a/spoolman/settings.py b/spoolman/settings.py
index 0c6ce3193..83427aa9d 100644
--- a/spoolman/settings.py
+++ b/spoolman/settings.py
@@ -68,6 +68,10 @@ def parse_setting(key: str) -> SettingDefinition:
 register_setting("extra_fields_vendor", SettingType.ARRAY, json.dumps([]))
 register_setting("extra_fields_filament", SettingType.ARRAY, json.dumps([]))
 register_setting("extra_fields_spool", SettingType.ARRAY, json.dumps([]))
+register_setting("derived_fields_vendor", SettingType.ARRAY, json.dumps([]))
+register_setting("derived_fields_filament", SettingType.ARRAY, json.dumps([]))
+register_setting("derived_fields_spool", SettingType.ARRAY, json.dumps([]))
+register_setting("api_include_derived_fields", SettingType.BOOLEAN, json.dumps(obj=False))
 register_setting("base_url", SettingType.STRING, json.dumps(""))
 
 register_setting("locations", SettingType.ARRAY, json.dumps([]))
diff --git a/tests_integration/tests/fields/json_logic_parity_fixtures.json b/tests_integration/tests/fields/json_logic_parity_fixtures.json
new file mode 100644
index 000000000..940d54b45
--- /dev/null
+++ b/tests_integration/tests/fields/json_logic_parity_fixtures.json
@@ -0,0 +1,142 @@
+[
+  {
+    "id": "n01_add",
+    "result_type": "number",
+    "expression_json": { "+": [1, 2, 3] },
+    "scope": {},
+    "expected": 6
+  },
+  {
+    "id": "n02_var_subtract",
+    "result_type": "number",
+    "expression_json": { "-": [{ "var": "weight" }, { "var": "remaining_weight" }] },
+    "scope": { "weight": 1000, "remaining_weight": 225 },
+    "expected": 775
+  },
+  {
+    "id": "n03_round_divide",
+    "result_type": "number",
+    "expression_json": { "round": [{ "/": [{ "var": "remaining_weight" }, 1000] }] },
+    "scope": { "remaining_weight": 225 },
+    "expected": 0
+  },
+  {
+    "id": "n04_abs_negative",
+    "result_type": "number",
+    "expression_json": { "abs": [-32] },
+    "scope": {},
+    "expected": 32
+  },
+  {
+    "id": "b01_and_true",
+    "result_type": "boolean",
+    "expression_json": { "and": [{ ">": [{ "var": "remaining_weight" }, 0] }, { "==": [{ "var": "archived" }, false] }] },
+    "scope": { "remaining_weight": 10, "archived": false },
+    "expected": true
+  },
+  {
+    "id": "b02_or_false",
+    "result_type": "boolean",
+    "expression_json": { "or": [{ "==": [{ "var": "material" }, "PLA" ] }, { "==": [{ "var": "material" }, "PETG"] }] },
+    "scope": { "material": "ABS" },
+    "expected": false
+  },
+  {
+    "id": "b03_if_branch",
+    "result_type": "boolean",
+    "expression_json": { "if": [{ ">=": [{ "var": "used_weight" }, 900] }, true, false] },
+    "scope": { "used_weight": 910 },
+    "expected": true
+  },
+  {
+    "id": "t01_concat",
+    "result_type": "text",
+    "expression_json": { "cat": ["Lot ", { "var": "lot_nr" }] },
+    "scope": { "lot_nr": "A123" },
+    "expected": "Lot A123"
+  },
+  {
+    "id": "t02_upper",
+    "result_type": "text",
+    "expression_json": { "upper": [{ "var": "material" }] },
+    "scope": { "material": "pla" },
+    "expected": "PLA"
+  },
+  {
+    "id": "t03_coalesce",
+    "result_type": "text",
+    "expression_json": { "coalesce": [{ "var": "extra.short_name" }, { "var": "name" }, "Unknown"] },
+    "scope": { "name": "Basic PLA" },
+    "expected": "Basic PLA"
+  },
+  {
+    "id": "d01_today",
+    "result_type": "date",
+    "expression_json": { "today": [] },
+    "scope": {},
+    "expected_shape": "yyyy-mm-dd"
+  },
+  {
+    "id": "d02_date_only",
+    "result_type": "date",
+    "expression_json": { "date_only": [{ "var": "created_at" }] },
+    "scope": { "created_at": "2026-02-28T10:15:00Z" },
+    "expected": "2026-02-28"
+  },
+  {
+    "id": "dt01_identity",
+    "result_type": "datetime",
+    "expression_json": { "var": "last_used" },
+    "scope": { "last_used": "2026-03-01T18:42:10Z" },
+    "expected": "2026-03-01T18:42:10Z"
+  },
+  {
+    "id": "tm01_time_only",
+    "result_type": "time",
+    "expression_json": { "time_only": [{ "var": "last_used" }] },
+    "scope": { "last_used": "2026-03-01T18:42:10Z" },
+    "expected": "18:42:10"
+  },
+  {
+    "id": "n05_days_between",
+    "result_type": "number",
+    "expression_json": { "days_between": [{ "var": "first_used" }, { "var": "last_used" }] },
+    "scope": { "first_used": "2026-03-01T00:00:00Z", "last_used": "2026-03-04T12:00:00Z" },
+    "expected": 3.5
+  },
+  {
+    "id": "n06_hours_between",
+    "result_type": "number",
+    "expression_json": { "hours_between": [{ "var": "first_used" }, { "var": "last_used" }] },
+    "scope": { "first_used": "2026-03-01T00:00:00Z", "last_used": "2026-03-01T18:00:00Z" },
+    "expected": 18
+  },
+  {
+    "id": "n07_hue_from_hex",
+    "result_type": "number",
+    "expression_json": { "hue_from_hex": ["#FF0000"] },
+    "scope": {},
+    "expected": 0
+  },
+  {
+    "id": "inv01_unknown_operator",
+    "result_type": "number",
+    "expression_json": { "sqrt": [9] },
+    "scope": {},
+    "expect_error": "operator_not_allowed"
+  },
+  {
+    "id": "inv02_missing_reference",
+    "result_type": "number",
+    "expression_json": { "+": [{ "var": "does_not_exist" }, 1] },
+    "scope": {},
+    "expect_error": "missing_reference"
+  },
+  {
+    "id": "inv03_type_mismatch",
+    "result_type": "number",
+    "expression_json": { "cat": ["a", "b"] },
+    "scope": {},
+    "expect_error": "result_type_mismatch"
+  }
+]
diff --git a/tests_integration/tests/fields/test_derived.py b/tests_integration/tests/fields/test_derived.py
new file mode 100644
index 000000000..b42f8f54a
--- /dev/null
+++ b/tests_integration/tests/fields/test_derived.py
@@ -0,0 +1,60 @@
+"""Integration tests for derived (formula) fields."""
+
+import httpx
+
+from ..conftest import URL, assert_httpx_code, assert_httpx_success
+
+
+def test_preview_derived_json_logic_expression():
+    """Preview endpoint should accept JSON Logic payloads."""
+    result = httpx.post(
+        f"{URL}/api/v1/field/derived/spool/preview",
+        json={
+            "expression_json": {"-": [{"var": "weight"}, {"var": "remaining_weight"}]},
+            "sample_values": {"weight": 1000, "remaining_weight": 225},
+        },
+    )
+    assert_httpx_success(result)
+    payload = result.json()
+    assert payload["result"] == 775
+    assert set(payload["references"]) == {"weight", "remaining_weight"}
+
+
+def test_create_and_delete_derived_json_logic_field():
+    """Derived fields should persist expression_json definitions."""
+    key = "json_logic_test_field"
+
+    create_result = httpx.post(
+        f"{URL}/api/v1/field/derived/spool/{key}",
+        json={
+            "name": "JSON Logic Test Field",
+            "description": "Created by integration test",
+            "result_type": "number",
+            "expression_json": {"+": [1, 2, 3]},
+            "surfaces": ["show"],
+            "allow_list_column_toggle": False,
+        },
+    )
+    assert_httpx_success(create_result)
+    fields = create_result.json()
+    created = next(field for field in fields if field["key"] == key)
+    assert created["expression_json"] == {"+": [1, 2, 3]}
+    # Transitional behavior keeps a string representation for legacy consumers that still read
+    # the expression column while JSON Logic is introduced.
+    assert created["expression"] is not None
+
+    delete_result = httpx.delete(f"{URL}/api/v1/field/derived/spool/{key}")
+    assert_httpx_success(delete_result)
+
+
+def test_preview_derived_json_logic_invalid_operator():
+    """Preview should reject unknown JSON Logic operators with HTTP 400."""
+    result = httpx.post(
+        f"{URL}/api/v1/field/derived/spool/preview",
+        json={
+            "expression_json": {"sqrt": [9]},
+            "sample_values": {},
+        },
+    )
+    assert_httpx_code(result, 400)
+    assert "not allowed" in result.json()["message"]
diff --git a/tests_integration/tests/fields/test_derived_api.py b/tests_integration/tests/fields/test_derived_api.py
new file mode 100644
index 000000000..fa507c45c
--- /dev/null
+++ b/tests_integration/tests/fields/test_derived_api.py
@@ -0,0 +1,98 @@
+"""Integration tests for derived field API payload exposure."""
+
+from typing import Any
+
+import httpx
+import pytest
+
+from ..conftest import URL, assert_httpx_success
+
+
+def _set_api_include_derived(enabled: bool | None) -> None:
+    if enabled is None:
+        result = httpx.post(f"{URL}/api/v1/setting/api_include_derived_fields", json="")
+    else:
+        result = httpx.post(
+            f"{URL}/api/v1/setting/api_include_derived_fields",
+            json="true" if enabled else "false",
+        )
+    assert_httpx_success(result)
+
+
+def _create_spool_formula_field(key: str, *, include_in_api: bool) -> None:
+    create_result = httpx.post(
+        f"{URL}/api/v1/field/derived/spool/{key}",
+        json={
+            "name": "API Derived Exposure Test",
+            "description": "Created by integration test",
+            "result_type": "number",
+            "expression_json": {"+": [{"var": "used_weight"}, {"var": "remaining_weight"}]},
+            "surfaces": ["show", "list"],
+            "allow_list_column_toggle": False,
+            "include_in_api": include_in_api,
+        },
+    )
+    assert_httpx_success(create_result)
+
+
+def _delete_spool_formula_field(key: str) -> None:
+    delete_result = httpx.delete(f"{URL}/api/v1/field/derived/spool/{key}")
+    assert_httpx_success(delete_result)
+
+
+def test_spool_api_include_derived_toggle(random_filament: dict[str, Any]):
+    """Derived API output should support default setting and per-request overrides."""
+    key = "api_include_derived_toggle"
+    hidden_key = "api_excluded_field"
+    _create_spool_formula_field(key, include_in_api=True)
+    _create_spool_formula_field(hidden_key, include_in_api=False)
+
+    spool_create = httpx.post(
+        f"{URL}/api/v1/spool",
+        json={
+            "filament_id": random_filament["id"],
+            "remaining_weight": 800,
+        },
+    )
+    assert_httpx_success(spool_create)
+    spool = spool_create.json()
+
+    try:
+        _set_api_include_derived(None)
+
+        default_response = httpx.get(f"{URL}/api/v1/spool/{spool['id']}")
+        assert_httpx_success(default_response)
+        assert "derived" not in default_response.json()
+
+        explicit_enabled_response = httpx.get(f"{URL}/api/v1/spool/{spool['id']}", params={"include_derived": "true"})
+        assert_httpx_success(explicit_enabled_response)
+        explicit_enabled_payload = explicit_enabled_response.json()
+        assert explicit_enabled_payload["derived"][key] == pytest.approx(1000)
+        assert hidden_key not in explicit_enabled_payload["derived"]
+
+        _set_api_include_derived(True)
+
+        default_enabled_response = httpx.get(f"{URL}/api/v1/spool/{spool['id']}")
+        assert_httpx_success(default_enabled_response)
+        default_enabled_payload = default_enabled_response.json()
+        assert default_enabled_payload["derived"][key] == pytest.approx(1000)
+        assert hidden_key not in default_enabled_payload["derived"]
+
+        explicit_disabled_response = httpx.get(f"{URL}/api/v1/spool/{spool['id']}", params={"include_derived": "false"})
+        assert_httpx_success(explicit_disabled_response)
+        assert "derived" not in explicit_disabled_response.json()
+
+        list_enabled_response = httpx.get(
+            f"{URL}/api/v1/spool",
+            params={"filament.id": str(random_filament["id"]), "include_derived": "true"},
+        )
+        assert_httpx_success(list_enabled_response)
+        list_payload = list_enabled_response.json()
+        matching_spool = next(item for item in list_payload if item["id"] == spool["id"])
+        assert matching_spool["derived"][key] == pytest.approx(1000)
+        assert hidden_key not in matching_spool["derived"]
+    finally:
+        httpx.delete(f"{URL}/api/v1/spool/{spool['id']}").raise_for_status()
+        _delete_spool_formula_field(hidden_key)
+        _delete_spool_formula_field(key)
+        _set_api_include_derived(None)

From ed9df0c0e4b170b63f6071492032e724c32cd435 Mon Sep 17 00:00:00 2001
From: akira69 <akira69@gmail.com>
Date: Tue, 10 Mar 2026 08:08:25 -0500
Subject: [PATCH 2/3] feat(formula-fields): UI improvements - consolidate help
 text to tooltips, remove clutter, add guidance icons

---
 client/public/locales/en/common.json          |   95 +-
 client/src/pages/filaments/list.tsx           |   20 +-
 client/src/pages/filaments/show.tsx           |    6 +-
 client/src/pages/help/index.tsx               |   45 +-
 .../pages/settings/complexFieldsSettings.tsx  | 1834 -----------
 .../pages/settings/extraFieldsSettings.tsx    |    2 +-
 .../pages/settings/formulaFieldsSettings.tsx  | 2711 +++++++++++++++++
 client/src/pages/spools/list.tsx              |   20 +-
 client/src/pages/spools/show.tsx              |    6 +-
 client/src/pages/vendors/list.tsx             |   20 +-
 client/src/pages/vendors/show.tsx             |    6 +-
 client/src/utils/formulaFields.ts             |   67 +-
 client/src/utils/queryFields.ts               |    3 +-
 scripts/pr-preflight.sh                       |  174 --
 spoolman/derived_fields.py                    |   20 +-
 15 files changed, 2903 insertions(+), 2126 deletions(-)
 delete mode 100644 client/src/pages/settings/complexFieldsSettings.tsx
 create mode 100644 client/src/pages/settings/formulaFieldsSettings.tsx
 delete mode 100755 scripts/pr-preflight.sh

diff --git a/client/public/locales/en/common.json b/client/public/locales/en/common.json
index 294ec7752..f4ef28375 100644
--- a/client/public/locales/en/common.json
+++ b/client/public/locales/en/common.json
@@ -362,48 +362,27 @@
             "delete_confirm": "Delete field {{name}}?",
             "delete_confirm_description": "This will delete the field and all associated data for all entities.",
             "delete_dependency_warning_intro": "Deleting this custom field will make dependent fields inoperable:",
-            "delete_dependency_warning_complex": "Complex extra fields: {{dependencies}}",
             "delete_dependency_warning_formula": "Formula extra fields: {{dependencies}}",
             "delete_dependency_warning_footer": "These entries remain saved, but behavior depending on this field will fail until references are updated."
         },
-        "complex_fields": {
-            "tab": "Complex Extra Fields",
-            "intro": "Complex extra fields are optional app-provided feature modules that extend built-in and custom fields for this entity. They are enabled here when available.",
-            "table_note": "Complex extra field definitions are provided by installed feature modules and are not created from this page.",
-            "missing_references_intro": "Some complex extra fields reference custom fields that are no longer available.",
-            "missing_references": "Missing custom extra field references: {{references}}",
-            "description": "<p>Complex fields add optional, pre-defined behaviors beyond custom extra fields.</p><p>Enabling one can add specialized display, actions, calculated values, or list columns for the selected entity. Disabled features remain hidden so the standard UI stays simpler.</p><p>Each entry below states exactly what enabling it adds. This framework can stay empty until a specific advanced feature is installed.</p>",
-            "tooltip": "Complex extra fields are app-provided feature modules. Enabling one can add specialized display, actions, calculated values, or list columns for this entity.",
+        "formula_fields": {
             "help_links": {
-                "complex": "Help: Complex Extra Fields",
                 "formula": "Help: Formula Extra Fields",
                 "formula_json": "Help: JSON Logic",
                 "formula_tokens": "Help: Token Groups"
             },
-            "empty": "No complex extra field feature modules are currently registered for this entity.",
             "available_functions": {
                 "label": "Token categories:",
                 "value": "Operators, helper functions, and field references are grouped in the editor."
             },
-            "columns": {
-                "name": "Name",
-                "description": "Feature",
-                "enable_description": "What Enabling Adds",
-                "surfaces": "Display In",
-                "enabled": "Enabled"
-            },
             "surfaces": {
-                "show": "Show",
+                "show": "Show Pages",
                 "edit": "Edit",
-                "list": "List",
-                "template": "Template",
+                "list": "Tables",
+                "template": "Template Selections",
                 "action": "Action",
                 "derived": "Derived"
             },
-            "messages": {
-                "enabled": "Enabled {{name}}.",
-                "disabled": "Disabled {{name}}."
-            },
             "formula": {
                 "header": "Formula Extra Fields",
                 "intro": "Formula extra fields are read-only derived values computed from expressions that reference existing fields.",
@@ -413,39 +392,46 @@
                 "empty": "No formula fields are currently defined for this entity.",
                 "columns": {
                     "key": "Key",
+                    "path": "Template & API Path",
                     "name": "Name",
                     "description": "Description",
-                    "result_type": "Result Type",
                     "expression": "Expression",
-                    "expression_json": "Expression JSON (JSON Logic)",
+                    "expression_json": "Formula Extra Field Expression (JSON Logic)",
                     "surfaces": "Display In",
-                    "allow_list_column_toggle": "Hide Columns Toggle",
                     "include_in_api": "Include in API"
                 },
+                "display_targets": {
+                    "show_pages": "Show Pages",
+                    "template_selections": "Template Selections",
+                    "tables": "Tables",
+                    "api": "API"
+                },
                 "types": {
                     "number": "Number",
                     "text": "Text"
                 },
-                "result_type_mismatch_hint": "Expression JSON appears to return {{inferred}}. You can keep the current type or auto-set it.",
-                "result_type_autoset": "Auto-set",
                 "tooltips": {
-                    "key": "Stable machine key for this formula field. It must be unique, uses lowercase letters/numbers/underscores, and is what later integrations will refer to.",
-                    "name": "Human-friendly label shown in the UI for this formula field.",
-                    "display_in": "Choose where this formula field is intended to appear later. Show means detail pages. List means table or list views. Template means label, title, or filename template variables.",
-                    "allow_list_column_toggle": "If enabled, list-display formula fields can be hidden or shown from the Hide Columns menu. If disabled, they stay visible whenever the field is shown in lists.",
-                    "include_in_api": "When enabled, this field can be included in API responses under payload.derived whenever include_derived is enabled for the request.",
-                    "expression_json": "JSON Logic object used to compute this formula field.",
-                    "sample_values": "Variable definition examples and formatting: {\"weight\": 1000, \"remaining_weight\": 225, \"created_at\": \"2026-02-28T10:15:00Z\", \"color_hex\": \"#FF00FF\"}"
+                    "key": "Unique identifier for this formula field. Uses lowercase letters, numbers, and underscores. Later integrations will reference it as 'derived.<key>'.",
+                    "name": "Human-friendly display label for this field in the UI.",
+                    "display_in": "Choose where this calculated field appears: in show/edit pages, tables, templates, or API responses.",
+                    "include_in_api": "When enabled, include this field in API responses under the derived object.",
+                    "expression_json": "JSON Logic expression that computes this field. Combine operators, helper functions, and field references below.",
+                    "sample_values": "Test data object to preview results. Provide sample values for all references used in your expression."
                 },
-                "allow_list_column_toggle_help": "Only applies when List display is selected. This keeps optional formula columns discoverable in the existing Hide Columns picker.",
-                "allow_list_column_toggle_inline": "Enable column visibility in {{entity}} view.",
+                "expression_json_copy_tooltip": "Copy expression JSON to clipboard",
+                "expression_json_copied": "Expression copied!",
                 "sample_values": "Sample Values (JSON)",
-                "sample_values_help": "Define JSON variables for preview/testing of this expression.",
-                "expression_json_help": "Enter a JSON Logic object manually or using helper/reference tokens and operators to insert snippets.",
+                "sample_values_help": "Enter a JSON object with key-value pairs matching your expression references",
+                "sample_values_detected_references": "Detected references:",
+                "sample_values_detected_references_empty": "No references detected yet",
+                "sample_values_reference_invalid": "Variable undefined or incorrectly defined in Sample Values JSON.",
+                "expression_json_help": "Enter a JSON Logic expression. Type manually or use the operator/helper/reference tokens below to build it step-by-step.",
                 "expression_json_example": "Example: {\"-\": [{\"var\": \"weight\"}, {\"var\": \"remaining_weight\"}]}",
                 "expression_json_required": "Expression JSON (JSON Logic) is required.",
-                "key_usage_help": "API/template path",
-                "key_reserved_hint": "This key matches a formula token name ({{key}}). It still works, but choosing a distinct key can reduce confusion.",
+                "expression_json_invalid": "Expression JSON must be valid JSON format (an object like {...}).",
+                "sample_values_invalid": "Sample Values must be valid JSON format (an object like {...}).",
+                "key_usage_help": "Template & API Path",
+                "key_reserved_hint": "This key matches a built-in operator or helper ({{key}}). It works, but a different name will be clearer for users.",
                 "operator_groups": {
                     "logical": "Logical / Conditional",
                     "comparison": "Comparison",
@@ -469,20 +455,27 @@
                 },
                 "reference_picker": {
                     "label": "Field References",
-                    "placeholder": "Pick a field to insert into the expression",
-                    "help": "Tokens are clickable inserts. Helper Functions are functional tokens, and Field References insert {var} references for built-in or configured extra fields."
+                    "placeholder": "Pick a field to insert as a reference",
+                    "help": "Click field references to insert them directly. Helper functions require you to select compatible references first. Both built-in fields and custom extra fields are available."
                 },
                 "json_builder": {
                     "operators_title": "Insert Tokens",
-                    "click_to_insert_help": "Select a helper, then select compatible field references. Field references insert JSON snippets immediately. Use Helper only to insert placeholder arguments.",
+                    "click_to_insert_help": "Click field references to insert them immediately. For helpers, select compatible references first, or use the 'Helper only' button to insert with placeholder arguments.",
                     "pending_helper": "Pending reference for helper {{helper}} ({{selected}}/{{total}})",
                     "pending_helper_prefix": "Pending reference for helper",
                     "pending_helper_count": "({{selected}}/{{total}})",
+                    "if_step_condition_operator": "Next: select IF condition operator",
+                    "if_step_condition_left": "Next: select IF condition left operand",
+                    "if_step_condition_right": "Next: select IF condition right operand",
+                    "if_step_then": "Next: select IF Then value",
+                    "if_step_else": "Next: select IF Else value",
                     "helper_unavailable_reason": "Helper {{helper}} has no compatible references for this entity yet.",
                     "helper_incompatible_reason": "Helper {{helper}} is incompatible with the currently selected pending reference type.",
                     "reference_incompatible_reason": "Selected reference is incompatible with helper {{helper}}.",
                     "show_operators": "Show operators",
                     "hide_operators": "Hide operators",
+                    "show_tokens": "Show tokens",
+                    "hide_tokens": "Hide tokens",
                     "operator_compact": {
                         "logical_top": "Logical",
                         "logical_bottom": "Conditional",
@@ -509,10 +502,12 @@
                 "missing_references_intro": "Some formula fields reference custom fields that are no longer available.",
                 "missing_references": "Missing custom field references: {{references}}",
                 "preview": {
-                    "button": "Preview Expression",
-                    "result_label": "Preview:",
-                    "references_used": "References used: {{references}}",
-                    "no_references": "No field references are used in this expression."
+                    "button": "Refresh",
+                    "loading": "Computing preview...",
+                    "panel_title": "Preview",
+                    "empty": "Waiting for valid expression/sample values.",
+                    "error_fallback": "Preview failed.",
+                    "refresh_tooltip": "Re-sync missing sample keys and immediately re-run preview."
                 }
             }
         }
diff --git a/client/src/pages/filaments/list.tsx b/client/src/pages/filaments/list.tsx
index fd05f9055..6112bad7c 100644
--- a/client/src/pages/filaments/list.tsx
+++ b/client/src/pages/filaments/list.tsx
@@ -26,7 +26,7 @@ import {
   useSpoolmanVendors,
 } from "../../components/otherModels";
 import { removeUndefined } from "../../utils/filtering";
-import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
+import { FormulaFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { TableState, useInitialTableState, useSavedState, useStoreInitialState } from "../../utils/saveload";
 import { useCurrencyFormatter } from "../../utils/settings";
 import { IFilament } from "./model";
@@ -147,16 +147,14 @@ export const FilamentList = () => {
   );
   const liveDataSource = useLiveify("filament", queryDataSource, collapseFilament);
   const listFormulaFields = useMemo(
-    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.list),
+    () => getFormulaFieldsForSurface(formulaFields.data, FormulaFieldSurface.list),
     [formulaFields.data],
   );
-  const toggleableListFormulaFields = useMemo(
-    () => listFormulaFields.filter((field) => field.allow_list_column_toggle),
-    [listFormulaFields],
-  );
+  // All list-surface formula fields are eligible for hide/show in the column picker,
+  // so we map every list formula to its derived column key here.
   const toggleableDerivedColumnKeys = useMemo(
-    () => toggleableListFormulaFields.map((field) => `derived.${field.key}`),
-    [toggleableListFormulaFields],
+    () => listFormulaFields.map((field) => `derived.${field.key}`),
+    [listFormulaFields],
   );
   const allColumnsWithExtraFields = useMemo(
     () => [
@@ -204,6 +202,8 @@ export const FilamentList = () => {
   };
 
   const updateColumnSelections = (selectedKeys: string[]) => {
+    // Persist core column visibility separately from derived-column visibility so
+    // derived keys can be toggled without rewriting the base showColumns state.
     setShowColumns(selectedKeys.filter((key) => !toggleableDerivedColumnKeys.includes(key)));
     setHiddenDerivedColumns(toggleableDerivedColumnKeys.filter((key) => !selectedKeys.includes(key)));
   };
@@ -235,7 +235,7 @@ export const FilamentList = () => {
                   };
                 }
                 if (column_id.indexOf("derived.") === 0) {
-                  const formulaField = toggleableListFormulaFields.find((field) => `derived.${field.key}` === column_id);
+                  const formulaField = listFormulaFields.find((field) => `derived.${field.key}` === column_id);
                   return {
                     key: column_id,
                     label: formulaField?.name ?? column_id,
@@ -388,7 +388,7 @@ export const FilamentList = () => {
           ...listFormulaFields.map(
             (field) => {
               const derivedColumnKey = `derived.${field.key}`;
-              if (field.allow_list_column_toggle && hiddenDerivedColumns.includes(derivedColumnKey)) {
+              if (hiddenDerivedColumns.includes(derivedColumnKey)) {
                 return undefined;
               }
 
diff --git a/client/src/pages/filaments/show.tsx b/client/src/pages/filaments/show.tsx
index 4c98fe19d..263e75914 100644
--- a/client/src/pages/filaments/show.tsx
+++ b/client/src/pages/filaments/show.tsx
@@ -10,7 +10,7 @@ import { NumberFieldUnit } from "../../components/numberField";
 import SpoolIcon from "../../components/spoolIcon";
 import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import { enrichText } from "../../utils/parsing";
-import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
+import { FormulaFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { useCurrencyFormatter } from "../../utils/settings";
 import { IFilament } from "./model";
 dayjs.extend(utc);
@@ -30,7 +30,7 @@ export const FilamentShow = () => {
 
   const record = data?.data;
   const showFormulaFields = useMemo(
-    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.show),
+    () => getFormulaFieldsForSurface(formulaFields.data, FormulaFieldSurface.show),
     [formulaFields.data],
   );
   const derivedValues = useMemo(
@@ -162,7 +162,7 @@ export const FilamentShow = () => {
       {extraFields?.data?.map((field, index) => (
         <ExtraFieldDisplay key={index} field={field} value={record?.extra[field.key]} />
       ))}
-      {showFormulaFields.length > 0 && <Title level={4}>{t("settings.complex_fields.formula.header")}</Title>}
+      {showFormulaFields.length > 0 && <Title level={4}>{t("settings.formula_fields.formula.header")}</Title>}
       {showFormulaFields.map((field) => (
         <Fragment key={field.key}>
           <Title level={5}>{field.name}</Title>
diff --git a/client/src/pages/help/index.tsx b/client/src/pages/help/index.tsx
index 3ee37bc86..e09f82f85 100644
--- a/client/src/pages/help/index.tsx
+++ b/client/src/pages/help/index.tsx
@@ -72,10 +72,11 @@ const BUILT_IN_FIELD_DEFINITIONS: Record<BuiltInEntity, BuiltInFieldDefinition[]
     { key: "comment", type: "text", intent: "Free-form notes about this manufacturer profile." },
   ],
 };
+// Keep help operator groups aligned with the interactive token panel in formula settings.
 const JSON_OPERATOR_GROUPS: Array<{ label: string; operators: string[] }> = [
   { label: "Logical / Conditional", operators: ["if", "and", "or", "!"] },
   { label: "Comparison", operators: ["==", "!=", "<", "<=", ">", ">="] },
-  { label: "Arithmetic", operators: ["+", "-", "*", "/", "%"] },
+  { label: "Arithmetic", operators: ["+", "-", "*", "/", "%", "floor"] },
 ];
 
 export const Help = () => {
@@ -306,13 +307,21 @@ export const Help = () => {
         <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
           Configure them in <Link to="/settings/extra/spool">Settings → Extra Fields</Link> for Spools, Filaments, or
           Manufacturers. In <Text strong>Formula Extra Fields</Text>, click <Text code>+</Text>, build your JSON
-          expression, then validate with <Text code>Sample Values (JSON)</Text> and <Text code>Preview Expression</Text>{" "}
-          before saving.
+          expression, then validate with <Text code>Sample Values (JSON)</Text> and <Text code>Refresh</Text> before
+          saving.
         </Paragraph>
         <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
-          In each formula field editor, use <Text strong>Include in API</Text> to mark that field as eligible for API
-          output. Entity responses include only those field-level opt-ins under a <Text code>derived</Text> object
-          whenever <Text code>include_derived=true</Text> is requested. Each field key is exposed as{" "}
+          In each formula field editor, <Text strong>Display In</Text> uses visible checkboxes for{" "}
+          <Text code>Show Pages</Text>, <Text code>Template Selections</Text>, and <Text code>Tables</Text>, with{" "}
+          <Text code>API</Text> in the same row for payload exposure.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          <Text code>Show Pages</Text> and <Text code>Tables</Text> display the field <Text strong>Name</Text> in UI.
+          Template/API integrations use the key path <Text code>{`derived.<key>`}</Text>.
+        </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
+          Entity responses include only field-level API opt-ins under a <Text code>derived</Text> object when
+          derived output is requested by the endpoint. Each field key is exposed as{" "}
           <Text code>{`derived.<key>`}</Text>.
         </Paragraph>
         <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel5Style }}>
@@ -406,7 +415,7 @@ export const Help = () => {
                         padding: 8,
                       }}
                     >
-                      <Text strong>{t(`settings.complex_fields.formula.token_categories.${group.key}`)}</Text>
+                      <Text strong>{t(`settings.formula_fields.formula.token_categories.${group.key}`)}</Text>
                       <div style={{ marginTop: 6 }}>
                         <Space size={[4, 4]} wrap>
                           {group.helpers.map((helper) => (
@@ -459,7 +468,7 @@ export const Help = () => {
                   padding: 10,
                 }}
               >
-                <Text strong>Example 2: Difference between two datetimes</Text>
+                <Text strong>Example 2: Completed days between two datetimes (integer)</Text>
                 <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 6 }}>
                   Variable definitions:
                 </Paragraph>
@@ -467,9 +476,9 @@ export const Help = () => {
                 <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 6 }}>
                   Expression JSON:
                 </Paragraph>
-                <Text code>{`{"days_between":[{"var":"first_used"},{"var":"last_used"}]}`}</Text>
+                <Text code>{`{"floor":[{"days_between":[{"var":"first_used"},{"var":"last_used"}]}]}`}</Text>
                 <Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: 8, marginBottom: 0 }}>
-                  Result: <Text code>{`8.25`}</Text>
+                  Result: <Text code>{`8`}</Text>
                 </Paragraph>
               </div>
               <div
@@ -500,7 +509,7 @@ export const Help = () => {
         </Title>
         <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
           The expression editor uses a JSON code editor (CodeMirror). Use <Text code>Format JSON</Text> to
-          auto-pretty-print your JSON Logic object. Keep <Text code>Preview Expression</Text> +{" "}
+          auto-pretty-print your JSON Logic object. Keep <Text code>Refresh</Text> +{" "}
           <Text code>Sample Values (JSON)</Text> as your first validation pass.
         </Paragraph>
         <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
@@ -508,6 +517,10 @@ export const Help = () => {
           keys without braces, and match keys to your <Text code>{`{"var":"..."}`}</Text> references. Example:{" "}
           <Text code>{`{"weight": 1000, "remaining_weight": 225, "created_at": "2026-02-28T10:15:00Z", "color_hex": "#FF00FF"}`}</Text>.
         </Paragraph>
+        <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
+          The editor also shows detected references from your expression and auto-scaffolds missing sample-value keys
+          without overwriting existing sample data. Use <Text code>Refresh</Text> to force a re-sync and preview run.
+        </Paragraph>
         <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
           Reference docs:{" "}
           <a href="https://jsonlogic.com/" target="_blank" rel="noreferrer">
@@ -523,16 +536,16 @@ export const Help = () => {
           </a>
         </Paragraph>
         <Paragraph type="secondary" style={{ ...sectionBodyStyle, ...nestedLevel6Style }}>
-          Choose where each formula appears: <Text code>Show</Text> (record details), <Text code>List</Text>{" "}
-          (table/list pages), and <Text code>Template</Text> (label/title/filename templates).
+          Choose where each formula appears: <Text code>Show Pages</Text> (record details),{" "}
+          <Text code>Tables</Text> (table/list pages), and <Text code>Template Selections</Text>{" "}
+          (label/title/filename templates).
         </Paragraph>
         <ul style={{ margin: "0 0 16px 56px", color: token.colorTextSecondary, lineHeight: 1.7, fontSize: token.fontSize }}>
           <li>
-            If a formula includes <Text code>List</Text>, you can enable column toggling so it can be hidden or shown
-            through <Text code>Hide Columns</Text> on list pages.
+            <Text code>Tables</Text> controls whether the formula appears in list/table pages at all.
           </li>
           <li>
-            If a formula includes <Text code>Template</Text>, it can be referenced in templates as{" "}
+            If a formula includes <Text code>Template Selections</Text>, it can be referenced in templates as{" "}
             <Text code>{`{derived.your_key}`}</Text> (for example, <Text code>{`{derived.days_between_events}`}</Text>).
           </li>
         </ul>
diff --git a/client/src/pages/settings/complexFieldsSettings.tsx b/client/src/pages/settings/complexFieldsSettings.tsx
deleted file mode 100644
index 0b95cac35..000000000
--- a/client/src/pages/settings/complexFieldsSettings.tsx
+++ /dev/null
@@ -1,1834 +0,0 @@
-import { json } from "@codemirror/lang-json";
-import { EditorView, drawSelection } from "@codemirror/view";
-import CodeMirror from "@uiw/react-codemirror";
-import {
-  CloseCircleOutlined,
-  MenuFoldOutlined,
-  MenuUnfoldOutlined,
-  PlusOutlined,
-  QuestionCircleOutlined,
-  WarningOutlined,
-} from "@ant-design/icons";
-import { useTranslate } from "@refinedev/core";
-import {
-  Button,
-  Col,
-  Divider,
-  Empty,
-  Flex,
-  Form,
-  Grid,
-  Input,
-  Modal,
-  Popconfirm,
-  Row,
-  Select,
-  Space,
-  Switch,
-  Table,
-  Tag,
-  Tooltip,
-  Typography,
-  message,
-  theme,
-} from "antd";
-import { ColumnType } from "antd/es/table";
-import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from "react";
-import { Link, useParams } from "react-router";
-import {
-  FORMULA_HELPER_GROUPS,
-  FORMULA_HELPERS,
-  FormulaHelperDefinition,
-  getExtraFieldReferences,
-} from "../../utils/formulaFields";
-import {
-  ComplexFieldSurface,
-  DerivedField,
-  DerivedFieldType,
-  EntityType,
-  FieldType,
-  useDeleteDerivedField,
-  useGetDerivedFields,
-  useGetFields,
-  usePreviewDerivedField,
-  useSetDerivedField,
-} from "../../utils/queryFields";
-
-const DERIVED_SURFACE_OPTIONS = [ComplexFieldSurface.show, ComplexFieldSurface.list, ComplexFieldSurface.template];
-const BUILTIN_REFERENCE_SUGGESTIONS: Record<EntityType, string[]> = {
-  vendor: ["id", "name", "registered", "comment"],
-  filament: ["id", "name", "material", "price", "density", "weight", "color_hex", "comment"],
-  spool: ["id", "weight", "remaining_weight", "used_weight", "price", "lot_nr", "comment", "created_at"],
-};
-const SAMPLE_VALUE_PLACEHOLDERS: Record<EntityType, string> = {
-  vendor: '{"name": "Example Vendor", "registered": "2026-02-28T10:15:00Z"}',
-  filament: '{"weight": 1000, "material": "PLA", "created_at": "2026-02-28T10:15:00Z", "color_hex": "#FF00FF"}',
-  spool: '{"weight": 1000, "remaining_weight": 225, "created_at": "2026-02-28T10:15:00Z"}',
-};
-const JSON_LOGIC_OPERATOR_GROUPS: Array<{ key: string; operators: string[] }> = [
-  { key: "logical", operators: ["if", "and", "or", "!"] },
-  { key: "comparison", operators: ["==", "!=", "<", "<=", ">", ">="] },
-  { key: "arithmetic", operators: ["+", "-", "*", "/", "%"] },
-];
-const OPERATOR_PANEL_WIDTH = 244;
-const INLINE_OPERATOR_PANEL_HEIGHT = 264;
-const HELPER_DESKTOP_COLUMN_LAYOUT: Array<{ top: string; bottom?: string }> = [
-  { top: "math", bottom: "color" },
-  { top: "text" },
-  { top: "datetime" },
-  { top: "dynamic", bottom: "date_diff" },
-];
-const JSON_LOGIC_OPERATOR_SNIPPETS: Record<string, string> = {
-  if: '{\n  "if": [\n    {"var": "condition"},\n    "then_value",\n    "else_value"\n  ]\n}',
-  and: '{\n  "and": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  or: '{\n  "or": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  "!": '{\n  "!": [\n    {"var": "value"}\n  ]\n}',
-  "==": '{\n  "==": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  "!=": '{\n  "!=": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  "<": '{\n  "<": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  "<=": '{\n  "<=": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  ">": '{\n  ">": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  ">=": '{\n  ">=": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  "+": '{\n  "+": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  "-": '{\n  "-": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  "*": '{\n  "*": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  "/": '{\n  "/": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-  "%": '{\n  "%": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
-};
-const RESERVED_DERIVED_KEY_NAMES = new Set([
-  ...JSON_LOGIC_OPERATOR_GROUPS.flatMap((group) => group.operators),
-  ...FORMULA_HELPERS.map((helper) => helper.name),
-]);
-
-type ReferenceValueKind = "any" | "number" | "datetime" | "text" | "boolean" | "range" | "unknown";
-type PendingHelperInsertState = {
-  helperName: string;
-  selectedReferences: string[];
-};
-type FormulaResultTypeHint = "number" | "text" | "boolean" | "unknown";
-
-const BUILTIN_REFERENCE_KIND_HINTS: Record<EntityType, Record<string, ReferenceValueKind>> = {
-  vendor: {
-    id: "number",
-    name: "text",
-    registered: "datetime",
-    comment: "text",
-  },
-  filament: {
-    id: "number",
-    name: "text",
-    material: "text",
-    price: "number",
-    density: "number",
-    weight: "number",
-    color_hex: "text",
-    comment: "text",
-  },
-  spool: {
-    id: "number",
-    weight: "number",
-    remaining_weight: "number",
-    used_weight: "number",
-    price: "number",
-    lot_nr: "text",
-    comment: "text",
-    created_at: "datetime",
-  },
-};
-
-function resolveColorLuminance(color: string): number | null {
-  const normalized = color.trim().toLowerCase();
-
-  const hexMatch = normalized.match(/^#([a-f0-9]{3,4}|[a-f0-9]{6}|[a-f0-9]{8})$/);
-  if (hexMatch) {
-    const hex = hexMatch[1];
-    const value =
-      hex.length === 3 || hex.length === 4
-        ? `${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}`
-        : hex.slice(0, 6);
-    const r = parseInt(value.slice(0, 2), 16);
-    const g = parseInt(value.slice(2, 4), 16);
-    const b = parseInt(value.slice(4, 6), 16);
-    return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
-  }
-
-  const rgbMatch = normalized.match(/^rgba?\(([^)]+)\)$/);
-  if (!rgbMatch) {
-    return null;
-  }
-  const channels = rgbMatch[1]
-    .split(",")
-    .map((part) => part.trim())
-    .slice(0, 3);
-  if (channels.length !== 3) {
-    return null;
-  }
-
-  const toByte = (channel: string): number | null => {
-    if (channel.endsWith("%")) {
-      const percent = Number(channel.slice(0, -1));
-      if (Number.isNaN(percent)) {
-        return null;
-      }
-      return Math.round((Math.max(0, Math.min(100, percent)) / 100) * 255);
-    }
-    const value = Number(channel);
-    if (Number.isNaN(value)) {
-      return null;
-    }
-    return Math.max(0, Math.min(255, value));
-  };
-
-  const r = toByte(channels[0]);
-  const g = toByte(channels[1]);
-  const b = toByte(channels[2]);
-  if (r == null || g == null || b == null) {
-    return null;
-  }
-  return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
-}
-
-function formatPreviewValue(value: string | number | boolean | null): string {
-  if (value === null) {
-    return "null";
-  }
-  return `${value}`;
-}
-
-function parseSampleValues(raw: string | undefined): Record<string, unknown> {
-  if (!raw || raw.trim() === "") {
-    return {};
-  }
-
-  const parsed = JSON.parse(raw);
-  if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
-    throw new Error("Sample values must be a JSON object.");
-  }
-
-  return parsed as Record<string, unknown>;
-}
-
-function parseExpressionJson(raw: string | undefined): Record<string, unknown> | undefined {
-  if (!raw || raw.trim() === "") {
-    return undefined;
-  }
-
-  const parsed = JSON.parse(raw);
-  if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
-    throw new Error("Expression JSON must be a JSON object.");
-  }
-  return parsed as Record<string, unknown>;
-}
-
-function mergeTypeHints(typeHints: FormulaResultTypeHint[]): FormulaResultTypeHint {
-  const knownHints = typeHints.filter((typeHint) => typeHint !== "unknown");
-  if (knownHints.length === 0) {
-    return "unknown";
-  }
-  return knownHints.every((typeHint) => typeHint === knownHints[0]) ? knownHints[0] : "unknown";
-}
-
-function inferExpressionJsonType(node: unknown): FormulaResultTypeHint {
-  if (typeof node === "number") {
-    return "number";
-  }
-  if (typeof node === "string") {
-    return "text";
-  }
-  if (typeof node === "boolean") {
-    return "boolean";
-  }
-  if (node === null || Array.isArray(node) || typeof node !== "object") {
-    return "unknown";
-  }
-
-  const entries = Object.entries(node as Record<string, unknown>);
-  if (entries.length !== 1) {
-    return "unknown";
-  }
-
-  const [operator, rawArgs] = entries[0];
-  const args = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
-
-  if (operator === "var") {
-    return "unknown";
-  }
-
-  if (operator === "if") {
-    const branchHints: FormulaResultTypeHint[] = [];
-    for (let index = 1; index < args.length; index += 2) {
-      branchHints.push(inferExpressionJsonType(args[index]));
-    }
-    if (args.length % 2 === 0 && args.length > 0) {
-      branchHints.push(inferExpressionJsonType(args[args.length - 1]));
-    }
-    return mergeTypeHints(branchHints);
-  }
-
-  if (operator === "coalesce") {
-    return mergeTypeHints(args.map((arg) => inferExpressionJsonType(arg)));
-  }
-
-  if (["==", "!=", "<", "<=", ">", ">=", "!", "and", "or"].includes(operator)) {
-    return "boolean";
-  }
-
-  if (
-    [
-      "+",
-      "-",
-      "*",
-      "/",
-      "%",
-      "abs",
-      "min",
-      "max",
-      "round",
-      "year",
-      "month",
-      "day",
-      "hour",
-      "minute",
-      "second",
-      "timestamp",
-      "days_between",
-      "hours_between",
-      "hue_from_hex",
-      "length",
-    ].includes(operator)
-  ) {
-    return "number";
-  }
-
-  if (["date_only", "time_only", "today", "cat", "concat", "replace", "trim", "upper", "lower", "left", "right"].includes(operator)) {
-    return "text";
-  }
-
-  return "unknown";
-}
-
-function toDerivedFieldType(typeHint: FormulaResultTypeHint): DerivedFieldType | null {
-  if (typeHint === "number") {
-    return DerivedFieldType.number;
-  }
-  if (typeHint === "text") {
-    return DerivedFieldType.text;
-  }
-  return null;
-}
-
-export function FormulaFieldsSettings() {
-  const { entityType } = useParams<{ entityType: EntityType }>();
-  const t = useTranslate();
-  const { token } = theme.useToken();
-  const screens = Grid.useBreakpoint();
-  const [messageApi, contextHolder] = message.useMessage();
-  const [derivedModalOpen, setDerivedModalOpen] = useState(false);
-  const [editingDerivedKey, setEditingDerivedKey] = useState<string | null>(null);
-  const [previewText, setPreviewText] = useState<string | null>(null);
-  const [previewReferences, setPreviewReferences] = useState<string[]>([]);
-  const [pendingJsonHelperInsert, setPendingJsonHelperInsert] = useState<PendingHelperInsertState | null>(null);
-  const [resultTypeMismatchHint, setResultTypeMismatchHint] = useState<DerivedFieldType | null>(null);
-  const [operatorPanelCollapsed, setOperatorPanelCollapsed] = useState(false);
-  const [hoveredTokenId, setHoveredTokenId] = useState<string | null>(null);
-  const [derivedForm] = Form.useForm();
-  const expressionJsonEditorRef = useRef<EditorView | null>(null);
-  const expressionJsonSelectionRef = useRef<{ from: number; to: number }>({ from: 0, to: 0 });
-
-  const selectedEntityType = entityType as EntityType;
-  const niceName = t(`${selectedEntityType}.${selectedEntityType}`);
-  const sectionBodyStyle = { marginTop: 0, fontSize: token.fontSize, lineHeight: 1.7 };
-  const tokenPanelStyle = useMemo(
-    () => ({
-      border: `1px solid ${token.colorBorderSecondary}`,
-      borderRadius: token.borderRadiusLG,
-      padding: 10,
-      background: token.colorBgContainer,
-    }),
-    [token.colorBgContainer, token.colorBorderSecondary, token.borderRadiusLG],
-  );
-  const tokenCategoryStyle = useMemo(
-    () => ({
-      borderRadius: token.borderRadius,
-      border: `1px solid ${token.colorBorderSecondary}`,
-      background: token.colorFillQuaternary,
-      padding: "8px 10px",
-      minHeight: 68,
-    }),
-    [token.borderRadius, token.colorBorderSecondary, token.colorFillQuaternary],
-  );
-  const tokenListStyle = useMemo<CSSProperties>(
-    () => ({
-      display: "flex",
-      flexWrap: "wrap",
-      gap: 6,
-      marginTop: 6,
-      justifyContent: "center",
-    }),
-    [],
-  );
-  const compactHelperCategoryStyle = useMemo<CSSProperties>(
-    () => ({
-      padding: "6px",
-      minHeight: 52,
-    }),
-    [],
-  );
-  const compactHelperTokenListStyle = useMemo<CSSProperties>(
-    () => ({
-      ...tokenListStyle,
-      justifyContent: "center",
-      marginTop: 4,
-      gap: 4,
-    }),
-    [tokenListStyle],
-  );
-  const referenceGridStyle = useMemo(
-    () => ({
-      display: "grid",
-      // Keep references dense while predictable: 4 columns on desktop, 3/2 on medium widths, 1 on mobile.
-      gridTemplateColumns: screens.lg || screens.xl || screens.xxl
-        ? "repeat(4, minmax(0, 1fr))"
-        : screens.md
-          ? "repeat(3, minmax(0, 1fr))"
-          : screens.sm
-            ? "repeat(2, minmax(0, 1fr))"
-            : "repeat(1, minmax(0, 1fr))",
-      gap: 6,
-    }),
-    [screens.lg, screens.md, screens.sm, screens.xl, screens.xxl],
-  );
-  const isDesktopLayout = Boolean(screens.lg || screens.xl || screens.xxl);
-  const isDesktopOperatorPanel = isDesktopLayout;
-  const showInlineOperatorPanel = Boolean(isDesktopOperatorPanel && !operatorPanelCollapsed);
-  const codeMirrorTheme = useMemo(() => {
-    const bgLuminance = resolveColorLuminance(token.colorBgContainer);
-    const textLuminance = resolveColorLuminance(token.colorText);
-    const isDark = bgLuminance != null ? bgLuminance < 0.5 : (textLuminance ?? 0) > 0.6;
-    // Use Ant warning background tokens so selection follows the theme palette,
-    // but stays muted enough for multiline editing in dark mode.
-    const selectionColor = isDark ? token.colorWarningBg : token.colorWarningBgHover;
-    const selectionMatchColor = isDark ? "rgba(250, 173, 20, 0.24)" : "rgba(250, 173, 20, 0.18)";
-    const activeLineColor = isDark ? "rgba(250, 173, 20, 0.02)" : "rgba(22, 119, 255, 0.04)";
-    const activeLineGutterColor = isDark ? "rgba(250, 173, 20, 0.04)" : "rgba(22, 119, 255, 0.06)";
-    // Force editor foreground/background directly from design tokens so formula JSON remains
-    // readable in both light and dark themes regardless of global CSS inheritance.
-    return EditorView.theme(
-      {
-        "&": {
-          backgroundColor: token.colorBgContainer,
-          color: token.colorText,
-          borderRadius: token.borderRadius,
-          border: `1px solid ${token.colorBorder}`,
-        },
-        "&.cm-editor": {
-          backgroundColor: token.colorBgContainer,
-          color: token.colorText,
-        },
-        "& .cm-scroller": {
-          backgroundColor: token.colorBgContainer,
-          color: token.colorText,
-        },
-        "&.cm-focused": {
-          outline: `1px solid ${token.colorPrimaryBorderHover}`,
-        },
-        ".cm-scroller": {
-          fontFamily: token.fontFamilyCode || "monospace",
-        },
-        ".cm-content, .cm-line": {
-          color: token.colorText,
-          caretColor: token.colorText,
-        },
-        ".cm-cursor, .cm-dropCursor": {
-          borderLeftColor: token.colorText,
-        },
-        // Keep bracket feedback enabled (standard editor behavior) but align it to amber theme.
-        ".cm-matchingBracket": {
-          backgroundColor: `${selectionMatchColor} !important`,
-          color: token.colorText,
-          outline: `1px solid ${token.colorWarningBorder}`,
-          borderRadius: 2,
-        },
-        ".cm-nonmatchingBracket": {
-          backgroundColor: "transparent !important",
-          color: token.colorError,
-          outline: `1px solid ${token.colorErrorBorder}`,
-          borderRadius: 2,
-        },
-        // Keep selection/search matches enabled (standard behavior), but use the same amber family.
-        ".cm-content .cm-selectionMatch, .cm-content .cm-searchMatch, .cm-content .cm-searchMatch-selected": {
-          backgroundColor: `${selectionMatchColor} !important`,
-          outline: `1px solid ${token.colorWarningBorder}`,
-          border: "none !important",
-          borderRadius: 2,
-          boxShadow: "none !important",
-        },
-        ".cm-gutters": {
-          backgroundColor: token.colorBgElevated,
-          color: token.colorTextTertiary,
-          borderRight: `1px solid ${token.colorBorderSecondary}`,
-        },
-        ".cm-activeLine": {
-          backgroundColor: activeLineColor,
-        },
-        ".cm-activeLineGutter": {
-          backgroundColor: activeLineGutterColor,
-        },
-        ".cm-selectionLayer": {
-          mixBlendMode: "normal",
-        },
-        // Force one consistent drawn selection color for both focused and blurred states.
-        ".cm-selectionBackground, .cm-selectionLayer .cm-selectionBackground, &.cm-focused .cm-selectionBackground, &.cm-focused .cm-selectionLayer .cm-selectionBackground": {
-          backgroundColor: `${selectionColor} !important`,
-          borderRadius: 2,
-        },
-        // Keep native browser selection transparent so it doesn't override with platform colors.
-        ".cm-content ::selection, .cm-line ::selection, .cm-line > span::selection, .cm-content *::selection": {
-          backgroundColor: "transparent !important",
-        },
-      },
-      { dark: isDark },
-    );
-  }, [
-    token.borderRadius,
-    token.colorBgContainer,
-    token.colorBgElevated,
-    token.colorBorder,
-    token.colorBorderSecondary,
-    token.colorError,
-    token.colorErrorBorder,
-    token.colorPrimaryBorderHover,
-    token.colorText,
-    token.colorTextTertiary,
-    token.colorWarningBorder,
-    token.colorWarningBg,
-    token.colorWarningBgHover,
-    token.fontFamilyCode,
-  ]);
-  useEffect(() => {
-    if (!isDesktopOperatorPanel) {
-      setOperatorPanelCollapsed(true);
-      return;
-    }
-    setOperatorPanelCollapsed(false);
-  }, [isDesktopOperatorPanel, derivedModalOpen]);
-
-  const derivedFields = useGetDerivedFields(selectedEntityType);
-  const configuredFields = useGetFields(selectedEntityType);
-  const setDerivedField = useSetDerivedField(selectedEntityType);
-  const deleteDerivedField = useDeleteDerivedField(selectedEntityType);
-  const previewDerivedField = usePreviewDerivedField(selectedEntityType);
-  const expressionJsonValue = Form.useWatch("expression_json", derivedForm) as string | undefined;
-  const derivedKeyValue = ((Form.useWatch("key", derivedForm) as string | undefined) || "").trim();
-  // Show the concrete API/template path for the currently typed key to remove
-  // ambiguity between formula operator names and field output identifiers.
-  const derivedKeyPath = useMemo(
-    () => (derivedKeyValue ? `derived.${derivedKeyValue}` : "derived.<key>"),
-    [derivedKeyValue],
-  );
-  const keyLooksLikeReservedToken = useMemo(
-    () => RESERVED_DERIVED_KEY_NAMES.has(derivedKeyValue),
-    [derivedKeyValue],
-  );
-
-  const sampleValuesPlaceholder = SAMPLE_VALUE_PLACEHOLDERS[selectedEntityType];
-
-  const labeledField = (labelKey: string, tooltipKey: string) => (
-    <Space size={4}>
-      <span>{t(labelKey)}</span>
-      <Tooltip title={t(tooltipKey)}>
-        <QuestionCircleOutlined />
-      </Tooltip>
-    </Space>
-  );
-
-  const referenceOptions = useMemo(() => {
-    const extraReferences = (configuredFields.data || []).map((field) => `extra.${field.key}`);
-    // Suggest both built-in fields and configured extra fields so users can compose formulas
-    // without memorizing the exact reference syntax for each entity.
-    return [...new Set([...BUILTIN_REFERENCE_SUGGESTIONS[selectedEntityType], ...extraReferences])];
-  }, [configuredFields.data, selectedEntityType]);
-  const compactReferenceOptions = useMemo(
-    () =>
-      referenceOptions.map((reference) => ({
-        value: reference,
-        label: `{${reference}}`,
-      })),
-    [referenceOptions],
-  );
-  const helperByName = useMemo(
-    () => Object.fromEntries(FORMULA_HELPERS.map((helper) => [helper.name, helper] as const)),
-    [],
-  );
-  const operatorGroups = useMemo(
-    () =>
-      JSON_LOGIC_OPERATOR_GROUPS.map((group) => ({
-        ...group,
-        label: t(`settings.complex_fields.formula.token_categories.${group.key}`),
-      })),
-    [t],
-  );
-  const helperGroups = useMemo(
-    () =>
-      FORMULA_HELPER_GROUPS.map((group) => ({
-        ...group,
-        label: t(`settings.complex_fields.formula.token_categories.${group.key}`),
-      })),
-    [t],
-  );
-  const helperGroupByKey = useMemo(
-    () => Object.fromEntries(helperGroups.map((group) => [group.key, group])),
-    [helperGroups],
-  );
-  const referenceKindByName = useMemo(() => {
-    const map: Record<string, ReferenceValueKind> = {
-      ...BUILTIN_REFERENCE_KIND_HINTS[selectedEntityType],
-    };
-
-    (configuredFields.data || []).forEach((field) => {
-      const fieldKind: ReferenceValueKind = (() => {
-        switch (field.field_type) {
-          case FieldType.integer:
-          case FieldType.float:
-            return "number";
-          case FieldType.datetime:
-            return "datetime";
-          case FieldType.boolean:
-            return "boolean";
-          case FieldType.integer_range:
-          case FieldType.float_range:
-            return "range";
-          case FieldType.text:
-          case FieldType.choice:
-            return "text";
-          default:
-            return "unknown";
-        }
-      })();
-      map[`extra.${field.key}`] = fieldKind;
-    });
-
-    return map;
-  }, [configuredFields.data, selectedEntityType]);
-  const getHelperReferenceCount = (helper: FormulaHelperDefinition): number => {
-    if (helper.insert_mode === "none") {
-      return 0;
-    }
-    return helper.reference_count ?? 1;
-  };
-  const helperAllowsReferenceKind = (helper: FormulaHelperDefinition, referenceKind: ReferenceValueKind): boolean => {
-    const requiredKind = helper.reference_kind ?? "any";
-    if (requiredKind === "any") {
-      return true;
-    }
-    return referenceKind === requiredKind;
-  };
-  const pendingHelperDefinition = useMemo(() => {
-    if (!pendingJsonHelperInsert) {
-      return null;
-    }
-    return helperByName[pendingJsonHelperInsert.helperName] || null;
-  }, [helperByName, pendingJsonHelperInsert]);
-  const getHelperDisabledReason = (helper: FormulaHelperDefinition): string | null => {
-    if (helper.insert_mode === "none") {
-      return null;
-    }
-
-    const requiredRefCount = getHelperReferenceCount(helper);
-    const compatibleReferences = referenceOptions.filter((reference) =>
-      helperAllowsReferenceKind(helper, referenceKindByName[reference] || "unknown"),
-    );
-    if (compatibleReferences.length < requiredRefCount) {
-      return t("settings.complex_fields.formula.json_builder.helper_unavailable_reason", { helper: helper.name });
-    }
-
-    // When the user already picked reference #1 for a pending helper, temporarily disable helper
-    // tokens that can't accept that selected reference kind. Clearing/completing pending insert
-    // resets all helper tokens back to normal.
-    if (pendingJsonHelperInsert?.selectedReferences.length) {
-      const selectedKind = referenceKindByName[pendingJsonHelperInsert.selectedReferences[0]] || "unknown";
-      if (!helperAllowsReferenceKind(helper, selectedKind)) {
-        return t("settings.complex_fields.formula.json_builder.helper_incompatible_reason", { helper: helper.name });
-      }
-    }
-
-    return null;
-  };
-  const isReferenceCompatibleWithPendingHelper = (reference: string): boolean => {
-    if (!pendingHelperDefinition) {
-      return true;
-    }
-    const referenceKind = referenceKindByName[reference] || "unknown";
-    return helperAllowsReferenceKind(pendingHelperDefinition, referenceKind);
-  };
-  const buildHelperPlaceholderArguments = (helper: FormulaHelperDefinition): Array<{ var: string }> => {
-    const referenceCount = getHelperReferenceCount(helper);
-    if (referenceCount <= 0) {
-      return [];
-    }
-    if (referenceCount === 1) {
-      return [{ var: "value" }];
-    }
-    if (referenceCount === 2) {
-      return [{ var: "start" }, { var: "end" }];
-    }
-    return Array.from({ length: referenceCount }, (_, index) => ({ var: `arg_${index + 1}` }));
-  };
-  const helperTokenGridStyle = useMemo<CSSProperties>(
-    () => ({
-      display: "grid",
-      // Desktop uses a dedicated stacked helper layout; this fallback handles narrower widths.
-      gridTemplateColumns: screens.md || screens.sm ? "repeat(2, minmax(0, 1fr))" : "repeat(1, minmax(0, 1fr))",
-      gap: 8,
-      alignItems: "start",
-    }),
-    [screens.md, screens.sm],
-  );
-  const renderTokenCategory = (
-    key: string,
-    label: string,
-    tokens: ReactNode,
-    style?: CSSProperties,
-    tokenContainerStyle?: CSSProperties,
-  ) => (
-    <div key={key} style={{ ...tokenCategoryStyle, ...style }}>
-      <Typography.Text type="secondary">
-        <strong>{label}</strong>
-      </Typography.Text>
-      <div style={tokenContainerStyle ?? tokenListStyle}>{tokens}</div>
-    </div>
-  );
-  const renderOperatorTokenGroups = (interactive: boolean) => (
-    <div style={{ display: "grid", gap: 6 }}>
-      {operatorGroups.map((group) => {
-        const compactTitle =
-          group.key === "logical"
-            ? (
-              <>
-                {t("settings.complex_fields.formula.json_builder.operator_compact.logical_top")}
-                <br />
-                {t("settings.complex_fields.formula.json_builder.operator_compact.logical_bottom")}
-              </>
-            )
-            : group.key === "comparison"
-              ? t("settings.complex_fields.formula.json_builder.operator_compact.comparison")
-              : t("settings.complex_fields.formula.json_builder.operator_compact.math");
-        const operatorGridColumns = group.key === "logical" ? "repeat(2, max-content)" : "repeat(3, max-content)";
-        const labelColumnWidth = group.key === "logical" ? 90 : 78;
-        return (
-          <div
-            key={group.key}
-            style={{
-              ...tokenCategoryStyle,
-              minHeight: 54,
-              padding: "6px 8px",
-              display: "grid",
-              gridTemplateColumns: `1fr ${labelColumnWidth}px`,
-              alignItems: "center",
-              columnGap: 6,
-            }}
-          >
-            <div
-              style={{
-                display: "grid",
-                gridTemplateColumns: operatorGridColumns,
-                gap: 3,
-                justifyItems: "center",
-                justifyContent: "start",
-              }}
-            >
-              {group.operators.map((operator) => (
-                (() => {
-                  const tokenId = `operator-${group.key}-${operator}`;
-                  const isHovered = hoveredTokenId === tokenId;
-                  return (
-                    <Typography.Text
-                      key={tokenId}
-                      code
-                      style={{
-                        cursor: interactive ? "pointer" : "default",
-                        minWidth: 20,
-                        textAlign: "center",
-                        whiteSpace: "nowrap",
-                        wordBreak: "normal",
-                        overflowWrap: "normal",
-                        color: interactive && isHovered ? token.colorWarningText : undefined,
-                        background: interactive && isHovered ? token.colorWarningBg : undefined,
-                        borderColor: interactive && isHovered ? token.colorWarningBorder : undefined,
-                        transition: "all 120ms ease-out",
-                      }}
-                      onMouseEnter={interactive ? () => setHoveredTokenId(tokenId) : undefined}
-                      onMouseLeave={interactive ? () => setHoveredTokenId((current) => (current === tokenId ? null : current)) : undefined}
-                      onClick={interactive ? () => insertExpressionJsonOperator(operator) : undefined}
-                    >
-                      {operator}
-                    </Typography.Text>
-                  );
-                })()
-              ))}
-            </div>
-            <Typography.Text type="secondary">
-              <strong style={{ lineHeight: 1.1, fontSize: "0.92em", whiteSpace: "nowrap", textAlign: "right", display: "block" }}>
-                {compactTitle}
-              </strong>
-            </Typography.Text>
-          </div>
-        );
-      })}
-    </div>
-  );
-  const renderHelperTokenCategory = (
-    groupKey: string,
-    interactive: boolean,
-    compact = false,
-  ) => {
-    const group = helperGroupByKey[groupKey];
-    if (!group || group.helpers.length === 0) {
-      return null;
-    }
-    return renderTokenCategory(
-      group.key,
-      group.label,
-      group.helpers.map((helper) => {
-        const disabledReason = interactive ? getHelperDisabledReason(helper) : null;
-        const tokenId = `helper-${helper.name}`;
-        const isHovered = hoveredTokenId === tokenId;
-        const helperToken = (
-          <Typography.Text
-            code
-            style={{
-              cursor: interactive ? (disabledReason ? "not-allowed" : "pointer") : "default",
-              opacity: disabledReason ? 0.45 : 1,
-              whiteSpace: "nowrap",
-              wordBreak: "normal",
-              overflowWrap: "normal",
-              flexShrink: 0,
-              color: interactive && !disabledReason && isHovered ? token.colorWarningText : undefined,
-              background: interactive && !disabledReason && isHovered ? token.colorWarningBg : undefined,
-              borderColor: interactive && !disabledReason && isHovered ? token.colorWarningBorder : undefined,
-              transition: "all 120ms ease-out",
-            }}
-            onMouseEnter={interactive && !disabledReason ? () => setHoveredTokenId(tokenId) : undefined}
-            onMouseLeave={interactive && !disabledReason ? () => setHoveredTokenId((current) => (current === tokenId ? null : current)) : undefined}
-            onClick={interactive && !disabledReason ? () => insertExpressionJsonHelper(helper) : undefined}
-          >
-            {helper.name}
-          </Typography.Text>
-        );
-        return (
-          <Tooltip key={`helper-${helper.name}`} title={interactive ? disabledReason || undefined : undefined}>
-            <span style={{ display: "inline-flex" }}>{helperToken}</span>
-          </Tooltip>
-        );
-      }),
-      compact ? compactHelperCategoryStyle : undefined,
-      compact ? compactHelperTokenListStyle : undefined,
-    );
-  };
-  const renderHelperTokenGroups = (interactive: boolean) => {
-    if (isDesktopLayout) {
-      return (
-        <div
-          style={{
-            display: "grid",
-            gridTemplateColumns: "repeat(4, minmax(0, 1fr))",
-            gap: 8,
-            alignItems: "start",
-          }}
-        >
-          {HELPER_DESKTOP_COLUMN_LAYOUT.map((column) => (
-            <div key={`helper-column-${column.top}`} style={{ display: "grid", gap: 8, alignContent: "start" }}>
-              {renderHelperTokenCategory(column.top, interactive)}
-              {column.bottom ? renderHelperTokenCategory(column.bottom, interactive, true) : null}
-            </div>
-          ))}
-        </div>
-      );
-    }
-    return (
-      <div style={helperTokenGridStyle}>
-        {helperGroups.map((group) => renderHelperTokenCategory(group.key, interactive))}
-      </div>
-    );
-  };
-
-  const missingCustomReferencesByDerivedField = useMemo(() => {
-    const availableCustomFieldKeys = new Set((configuredFields.data || []).map((field) => field.key));
-    const missingMap: Record<string, string[]> = {};
-
-    (derivedFields.data || []).forEach((derivedField) => {
-      const missingReferences = getExtraFieldReferences(derivedField.expression_json || undefined).filter(
-        (reference) => !availableCustomFieldKeys.has(reference),
-      );
-      if (missingReferences.length > 0) {
-        missingMap[derivedField.key] = missingReferences;
-      }
-    });
-
-    return missingMap;
-  }, [configuredFields.data, derivedFields.data]);
-
-  const hasBrokenFormulaDependencies = useMemo(
-    () => Object.keys(missingCustomReferencesByDerivedField).length > 0,
-    [missingCustomReferencesByDerivedField],
-  );
-
-  const openCreateDerived = () => {
-    setEditingDerivedKey(null);
-    setPreviewText(null);
-    setPreviewReferences([]);
-    setResultTypeMismatchHint(null);
-    derivedForm.resetFields();
-    derivedForm.setFieldsValue({
-      key: "",
-      name: "",
-      description: "",
-      result_type: DerivedFieldType.number,
-      surfaces: [ComplexFieldSurface.show],
-      allow_list_column_toggle: false,
-      include_in_api: false,
-      expression_json: "",
-      sample_values: "{}",
-    });
-    setDerivedModalOpen(true);
-  };
-
-  const openEditDerived = (record: DerivedField) => {
-    setEditingDerivedKey(record.key);
-    setPreviewText(null);
-    setPreviewReferences([]);
-    setResultTypeMismatchHint(null);
-    derivedForm.setFieldsValue({
-      key: record.key,
-      name: record.name,
-      description: record.description || "",
-      result_type: record.result_type,
-      surfaces: record.surfaces,
-      allow_list_column_toggle: record.allow_list_column_toggle,
-      include_in_api: record.include_in_api ?? false,
-      expression_json: record.expression_json ? JSON.stringify(record.expression_json, null, 2) : "",
-      sample_values: "{}",
-    });
-    setDerivedModalOpen(true);
-  };
-
-  const closeDerivedModal = () => {
-    setDerivedModalOpen(false);
-    setEditingDerivedKey(null);
-    setPreviewText(null);
-    setPreviewReferences([]);
-    setResultTypeMismatchHint(null);
-    setPendingJsonHelperInsert(null);
-    expressionJsonSelectionRef.current = { from: 0, to: 0 };
-    derivedForm.resetFields();
-  };
-
-  const insertExpressionJsonSnippet = (snippet: string) => {
-    const currentValue = (derivedForm.getFieldValue("expression_json") as string | undefined) || "";
-    const hasEditor = expressionJsonEditorRef.current !== null;
-    if (!hasEditor) {
-      const prefix = currentValue.trim() === "" ? "" : "\n";
-      derivedForm.setFieldValue("expression_json", `${currentValue}${prefix}${snippet}`);
-      return;
-    }
-
-    const start = expressionJsonSelectionRef.current.from;
-    const end = expressionJsonSelectionRef.current.to;
-    const nextValue = `${currentValue.slice(0, start)}${snippet}${currentValue.slice(end)}`;
-    const nextCursor = start + snippet.length;
-    derivedForm.setFieldValue("expression_json", nextValue);
-    expressionJsonSelectionRef.current = { from: nextCursor, to: nextCursor };
-
-    requestAnimationFrame(() => {
-      const editor = expressionJsonEditorRef.current;
-      if (!editor) {
-        return;
-      }
-      editor.focus();
-      editor.dispatch({
-        selection: { anchor: nextCursor, head: nextCursor },
-        scrollIntoView: true,
-      });
-    });
-  };
-
-  const insertExpressionJsonReference = (reference: string) => {
-    if (!pendingHelperDefinition) {
-      insertExpressionJsonSnippet(JSON.stringify({ var: reference }, null, 2));
-      return;
-    }
-
-    if (!isReferenceCompatibleWithPendingHelper(reference)) {
-      messageApi.warning(
-        t("settings.complex_fields.formula.json_builder.reference_incompatible_reason", {
-          helper: pendingHelperDefinition.name,
-        }),
-      );
-      return;
-    }
-
-    const pendingState = pendingJsonHelperInsert;
-    if (!pendingState) {
-      return;
-    }
-    const requiredReferenceCount = getHelperReferenceCount(pendingHelperDefinition);
-    const selectedReferences = [...pendingState.selectedReferences, reference];
-    if (selectedReferences.length < requiredReferenceCount) {
-      setPendingJsonHelperInsert({
-        helperName: pendingHelperDefinition.name,
-        selectedReferences,
-      });
-      return;
-    }
-
-    const snippet = {
-      [pendingHelperDefinition.name]: selectedReferences
-        .slice(0, requiredReferenceCount)
-        .map((selectedReference) => ({ var: selectedReference })),
-    };
-    // Insert ready-to-parse JSON Logic objects so users can build expressions without memorizing
-    // raw AST syntax.
-    insertExpressionJsonSnippet(JSON.stringify(snippet, null, 2));
-    setPendingJsonHelperInsert(null);
-  };
-
-  const insertExpressionJsonHelper = (helper: FormulaHelperDefinition) => {
-    if (helper.insert_mode === "none") {
-      insertExpressionJsonSnippet(JSON.stringify({ [helper.name]: [] }, null, 2));
-      setPendingJsonHelperInsert(null);
-      return;
-    }
-    const disabledReason = getHelperDisabledReason(helper);
-    if (disabledReason) {
-      messageApi.warning(disabledReason);
-      return;
-    }
-    // Keep helper insertion staged until required reference tokens are selected, so helpers with
-    // multiple reference operands (for example days_between/hours_between) can be assembled safely.
-    setPendingJsonHelperInsert({ helperName: helper.name, selectedReferences: [] });
-    messageApi.info(
-      t("settings.complex_fields.formula.json_builder.pending_helper", {
-        helper: helper.name,
-        selected: 0,
-        total: getHelperReferenceCount(helper),
-      }),
-    );
-  };
-
-  const insertPendingHelperWithoutReferences = () => {
-    if (!pendingHelperDefinition) {
-      return;
-    }
-    const placeholderSnippet = {
-      [pendingHelperDefinition.name]: buildHelperPlaceholderArguments(pendingHelperDefinition),
-    };
-    insertExpressionJsonSnippet(JSON.stringify(placeholderSnippet, null, 2));
-    setPendingJsonHelperInsert(null);
-  };
-  const cancelPendingHelperInsert = () => {
-    setPendingJsonHelperInsert(null);
-  };
-
-  const insertExpressionJsonOperator = (operator: string) => {
-    const snippet = JSON_LOGIC_OPERATOR_SNIPPETS[operator];
-    if (!snippet) {
-      return;
-    }
-    insertExpressionJsonSnippet(snippet);
-    setPendingJsonHelperInsert(null);
-  };
-
-  const formatExpressionJson = async () => {
-    try {
-      const currentValue = (derivedForm.getFieldValue("expression_json") as string | undefined) || "";
-      const parsed = parseExpressionJson(currentValue);
-      if (!parsed) {
-        setResultTypeMismatchHint(null);
-        return;
-      }
-      const selectedResultType = derivedForm.getFieldValue("result_type") as DerivedFieldType | undefined;
-      const inferredType = toDerivedFieldType(inferExpressionJsonType(parsed));
-      if (selectedResultType && inferredType && inferredType !== selectedResultType) {
-        setResultTypeMismatchHint(inferredType);
-      } else {
-        setResultTypeMismatchHint(null);
-      }
-      derivedForm.setFieldValue("expression_json", JSON.stringify(parsed, null, 2));
-      messageApi.success(t("settings.complex_fields.formula.json_builder.formatted"));
-    } catch (errInfo) {
-      if (errInfo instanceof Error) {
-        messageApi.error(errInfo.message);
-      }
-    }
-  };
-
-  const saveDerived = async () => {
-    try {
-      const values = await derivedForm.validateFields();
-      const key = editingDerivedKey || values.key;
-      const expressionJson = parseExpressionJson(values.expression_json);
-      if (!expressionJson) {
-        throw new Error(t("settings.complex_fields.formula.expression_json_required"));
-      }
-      if (expressionJson) {
-        const inferredType = toDerivedFieldType(inferExpressionJsonType(expressionJson));
-        if (inferredType && inferredType !== values.result_type) {
-          setResultTypeMismatchHint(inferredType);
-        } else {
-          setResultTypeMismatchHint(null);
-        }
-      } else {
-        setResultTypeMismatchHint(null);
-      }
-
-      await setDerivedField.mutateAsync({
-        key,
-        params: {
-          name: values.name,
-          description: values.description || undefined,
-          result_type: values.result_type,
-          expression_json: expressionJson,
-          surfaces: values.surfaces,
-          allow_list_column_toggle: values.allow_list_column_toggle,
-          include_in_api: values.include_in_api ?? false,
-        },
-      });
-
-      messageApi.success(
-        t(editingDerivedKey ? "settings.complex_fields.formula.messages.updated" : "settings.complex_fields.formula.messages.created", {
-          name: values.name,
-        }),
-      );
-      closeDerivedModal();
-    } catch (errInfo) {
-      if (errInfo instanceof Error) {
-        messageApi.error(errInfo.message);
-      }
-    }
-  };
-
-  const previewDerived = async () => {
-    try {
-      const values = await derivedForm.validateFields(["expression_json", "sample_values"]);
-      const sampleValues = parseSampleValues(values.sample_values);
-      const expressionJson = parseExpressionJson(values.expression_json);
-      if (!expressionJson) {
-        throw new Error(t("settings.complex_fields.formula.expression_json_required"));
-      }
-      // Preview uses sample JSON only as a sandbox for validating formulas before they are exposed
-      // on show/list/template surfaces.
-      const preview = await previewDerivedField.mutateAsync({
-        expression_json: expressionJson,
-        sample_values: sampleValues,
-      });
-
-      setPreviewText(formatPreviewValue(preview.result));
-      setPreviewReferences(preview.references);
-    } catch (errInfo) {
-      if (errInfo instanceof Error) {
-        messageApi.error(errInfo.message);
-      }
-    }
-  };
-
-  const removeDerived = async (record: DerivedField) => {
-    try {
-      await deleteDerivedField.mutateAsync(record.key);
-      messageApi.success(t("settings.complex_fields.formula.messages.deleted", { name: record.name }));
-    } catch (errInfo) {
-      if (errInfo instanceof Error) {
-        messageApi.error(errInfo.message);
-      }
-    }
-  };
-
-  const derivedColumns: ColumnType<DerivedField>[] = [
-    {
-      title: t("settings.complex_fields.formula.columns.key"),
-      dataIndex: "key",
-      key: "key",
-      width: "12%",
-    },
-    {
-      title: t("settings.complex_fields.formula.columns.name"),
-      dataIndex: "name",
-      key: "name",
-      width: "16%",
-    },
-    {
-      title: t("settings.complex_fields.formula.columns.result_type"),
-      dataIndex: "result_type",
-      key: "result_type",
-      width: "10%",
-      render: (value: DerivedFieldType) => t(`settings.complex_fields.formula.types.${value}`),
-    },
-    {
-      title: t("settings.complex_fields.formula.columns.expression"),
-      dataIndex: "expression_json",
-      key: "expression",
-      width: "30%",
-      render: (_value: Record<string, unknown> | undefined, record) => {
-        const expressionValue = record.expression_json ? JSON.stringify(record.expression_json) : "";
-        const missingReferences = missingCustomReferencesByDerivedField[record.key] || [];
-        return (
-          <Space direction="vertical" size={4}>
-            <Typography.Text code style={{ whiteSpace: "normal", wordBreak: "break-word" }}>
-              {expressionValue}
-            </Typography.Text>
-            {missingReferences.length > 0 && (
-              <Typography.Text type="danger">
-                {t("settings.complex_fields.formula.missing_references", {
-                  references: missingReferences.join(", "),
-                })}
-              </Typography.Text>
-            )}
-          </Space>
-        );
-      },
-    },
-    {
-      title: t("settings.complex_fields.formula.columns.surfaces"),
-      dataIndex: "surfaces",
-      key: "surfaces",
-      width: "16%",
-      render: (surfaces: string[]) => (
-        <Space size={[4, 4]} wrap>
-          {surfaces.map((surface) => (
-            <Tag key={surface}>{t(`settings.complex_fields.surfaces.${surface}`)}</Tag>
-          ))}
-        </Space>
-      ),
-    },
-    {
-      title: t("settings.complex_fields.formula.columns.include_in_api"),
-      dataIndex: "include_in_api",
-      key: "include_in_api",
-      width: "10%",
-      render: (value: boolean) => (value ? <Tag color="processing">API</Tag> : <Tag>{t("no")}</Tag>),
-    },
-    {
-      title: "",
-      key: "operation",
-      width: "16%",
-      render: (_: unknown, record) => (
-        <Space>
-          <Button onClick={() => openEditDerived(record)} size="small">
-            {t("buttons.edit")}
-          </Button>
-          <Popconfirm
-            title={t("settings.complex_fields.formula.delete_confirm", { name: record.name })}
-            onConfirm={() => removeDerived(record)}
-            okText={t("buttons.delete")}
-            cancelText={t("buttons.cancel")}
-          >
-            <Button danger size="small">
-              {t("buttons.delete")}
-            </Button>
-          </Popconfirm>
-        </Space>
-      ),
-    },
-  ];
-
-  const previewSummary = useMemo(() => {
-    if (previewText == null) {
-      return null;
-    }
-
-    const referencesText =
-      previewReferences.length > 0
-        ? t("settings.complex_fields.formula.preview.references_used", {
-            references: previewReferences.join(", "),
-          })
-        : t("settings.complex_fields.formula.preview.no_references");
-
-    return (
-      <Typography.Paragraph
-        style={{
-          marginBottom: 0,
-        }}
-      >
-        <strong>{t("settings.complex_fields.formula.preview.result_label")}</strong> {previewText}
-        <br />
-        {referencesText}
-      </Typography.Paragraph>
-    );
-  }, [previewReferences, previewText, t]);
-  const pendingHelperHint = useMemo(() => {
-    if (!pendingHelperDefinition || !pendingJsonHelperInsert) {
-      return null;
-    }
-    const selected = pendingJsonHelperInsert.selectedReferences.length;
-    const total = getHelperReferenceCount(pendingHelperDefinition);
-    return {
-      helper: pendingHelperDefinition.name,
-      selected,
-      total,
-    };
-  }, [pendingHelperDefinition, pendingJsonHelperInsert]);
-  return (
-    <>
-      <Divider orientation="left" plain>
-        <Space size={8}>
-          <span>
-            {t("settings.complex_fields.formula.header")}: {niceName}
-          </span>
-          <Tooltip title={t("settings.complex_fields.formula.tooltip")}>
-            <QuestionCircleOutlined />
-          </Tooltip>
-          <Link
-            style={{
-              fontSize: "0.85em",
-            }}
-            to="/help#formula-fields"
-          >
-            {t("settings.complex_fields.help_links.formula")}
-          </Link>
-        </Space>
-      </Divider>
-      <Typography.Paragraph type="secondary" style={sectionBodyStyle}>
-        {t("settings.complex_fields.formula.intro")}
-      </Typography.Paragraph>
-      <Typography.Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: -8 }}>
-        {t("settings.complex_fields.formula.evaluation_model_help")}
-      </Typography.Paragraph>
-      {hasBrokenFormulaDependencies && (
-        <Typography.Paragraph type="danger" style={{ marginTop: 0 }}>
-          {t("settings.complex_fields.formula.missing_references_intro")}
-        </Typography.Paragraph>
-      )}
-      <Typography.Paragraph type="secondary" style={{ ...sectionBodyStyle, marginBottom: 12 }}>
-        {t("settings.complex_fields.available_functions.value")}
-      </Typography.Paragraph>
-      <Table
-        columns={derivedColumns}
-        dataSource={derivedFields.data || []}
-        loading={derivedFields.isLoading}
-        pagination={false}
-        locale={{
-          emptyText: (
-            <Empty
-              description={t("settings.complex_fields.formula.empty")}
-              image={Empty.PRESENTED_IMAGE_SIMPLE}
-            />
-          ),
-        }}
-        onRow={(record) => {
-          const hasMissingReferences = (missingCustomReferencesByDerivedField[record.key] || []).length > 0;
-          if (!hasMissingReferences) {
-            return {};
-          }
-          return {
-            style: {
-              backgroundColor: token.colorErrorBg,
-            },
-          };
-        }}
-        rowKey="key"
-      />
-      <Flex justify="center">
-        <Button
-          type="primary"
-          shape="circle"
-          icon={<PlusOutlined />}
-          size="large"
-          style={{
-            margin: "1em",
-          }}
-          onClick={() => openCreateDerived()}
-        />
-      </Flex>
-
-      <Modal
-        destroyOnHidden
-        onCancel={() => closeDerivedModal()}
-        onOk={() => saveDerived()}
-        open={derivedModalOpen}
-        okText={t("buttons.save")}
-        cancelText={t("buttons.cancel")}
-        title={`${t(
-          editingDerivedKey
-            ? "settings.complex_fields.formula.modal.edit_title"
-            : "settings.complex_fields.formula.modal.create_title",
-        )}: ${niceName}`}
-        width={820}
-      >
-        <Form
-          form={derivedForm}
-          layout="vertical"
-          initialValues={{
-            result_type: DerivedFieldType.number,
-            surfaces: [ComplexFieldSurface.show],
-            allow_list_column_toggle: false,
-            include_in_api: false,
-            expression_json: "",
-            sample_values: "{}",
-          }}
-        >
-          {/* Responsive split: two columns on medium+ screens, stacked flow on narrow/mobile widths. */}
-          <Row gutter={12}>
-            <Col xs={24} md={12}>
-              <Form.Item
-                label={labeledField(
-                  "settings.complex_fields.formula.columns.key",
-                  "settings.complex_fields.formula.tooltips.key",
-                )}
-                name="key"
-                extra={(
-                  <Space direction="vertical" size={2} style={{ width: "100%" }}>
-                    <Typography.Text type="secondary">
-                      {t("settings.complex_fields.formula.key_usage_help")}: <Typography.Text code>{derivedKeyPath}</Typography.Text>
-                    </Typography.Text>
-                    {keyLooksLikeReservedToken && (
-                      <Typography.Text type="warning">
-                        <WarningOutlined style={{ marginRight: 6 }} />
-                        {t("settings.complex_fields.formula.key_reserved_hint", { key: derivedKeyValue })}
-                      </Typography.Text>
-                    )}
-                  </Space>
-                )}
-                rules={[
-                  { required: true, min: 1, max: 64, pattern: /^[a-z0-9_]+$/ },
-                  {
-                    validator: async (_, value) => {
-                      if (!editingDerivedKey && derivedFields.data?.some((field) => field.key === value)) {
-                        throw new Error(t("settings.extra_fields.non_unique_key_error"));
-                      }
-                    },
-                  },
-                ]}
-              >
-                <Input disabled={editingDerivedKey != null} />
-              </Form.Item>
-            </Col>
-            <Col xs={24} md={12}>
-              <Form.Item
-                label={labeledField(
-                  "settings.complex_fields.formula.columns.name",
-                  "settings.complex_fields.formula.tooltips.name",
-                )}
-                name="name"
-                rules={[{ required: true, min: 1, max: 128 }]}
-              >
-                <Input />
-              </Form.Item>
-            </Col>
-          </Row>
-          <Form.Item label={t("settings.complex_fields.formula.columns.description")} name="description" rules={[{ max: 512 }]}>
-            <Input.TextArea autoSize={{ minRows: 2, maxRows: 4 }} />
-          </Form.Item>
-          {/* Keep Display In aligned with Result Type on desktop while preserving form order when stacked. */}
-          <Row gutter={12}>
-            <Col xs={24} md={12}>
-              <Form.Item
-                label={(
-                  <Space size={6}>
-                    <span>{t("settings.complex_fields.formula.columns.result_type")}</span>
-                    {resultTypeMismatchHint && (
-                      <>
-                        <Tooltip
-                          title={t("settings.complex_fields.formula.result_type_mismatch_hint", {
-                            inferred: t(`settings.complex_fields.formula.types.${resultTypeMismatchHint}`),
-                          })}
-                        >
-                          <WarningOutlined style={{ color: token.colorWarning }} />
-                        </Tooltip>
-                        <Button
-                          type="link"
-                          size="small"
-                          style={{ padding: 0, height: "auto", lineHeight: 1 }}
-                          onClick={() => {
-                            derivedForm.setFieldValue("result_type", resultTypeMismatchHint);
-                            setResultTypeMismatchHint(null);
-                          }}
-                        >
-                          {t("settings.complex_fields.formula.result_type_autoset")}
-                        </Button>
-                      </>
-                    )}
-                  </Space>
-                )}
-                name="result_type"
-                rules={[{ required: true }]}
-              >
-                <Select
-                  options={[
-                    { label: t("settings.complex_fields.formula.types.number"), value: DerivedFieldType.number },
-                    { label: t("settings.complex_fields.formula.types.text"), value: DerivedFieldType.text },
-                  ]}
-                />
-              </Form.Item>
-            </Col>
-            <Col xs={24} md={12}>
-              <Form.Item
-                label={labeledField(
-                  "settings.complex_fields.formula.columns.surfaces",
-                  "settings.complex_fields.formula.tooltips.display_in",
-                )}
-                required
-              >
-                <Flex gap={12} align="center" wrap>
-                  <Form.Item name="surfaces" rules={[{ required: true, type: "array", min: 1 }]} noStyle>
-                    <Select
-                      mode="multiple"
-                      style={{ width: "100%" }}
-                      options={DERIVED_SURFACE_OPTIONS.map((surface) => ({
-                        label: t(`settings.complex_fields.surfaces.${surface}`),
-                        value: surface,
-                      }))}
-                      onChange={(selected: string[]) => {
-                        if (!selected.includes(ComplexFieldSurface.list)) {
-                          derivedForm.setFieldValue("allow_list_column_toggle", false);
-                        }
-                      }}
-                    />
-                  </Form.Item>
-                  <Form.Item shouldUpdate noStyle>
-                    {({ getFieldValue }) => {
-                      const selectedSurfaces = (getFieldValue("surfaces") as string[] | undefined) || [];
-                      const listEnabled = selectedSurfaces.includes(ComplexFieldSurface.list);
-                      if (!listEnabled) {
-                        return null;
-                      }
-
-                      return (
-                        <Space size={8}>
-                          <Form.Item name="allow_list_column_toggle" valuePropName="checked" noStyle>
-                            <Switch />
-                          </Form.Item>
-                          <Typography.Text type="secondary" style={{ whiteSpace: "nowrap" }}>
-                            {t("settings.complex_fields.formula.allow_list_column_toggle_inline", { entity: niceName })}
-                          </Typography.Text>
-                        </Space>
-                      );
-                    }}
-                  </Form.Item>
-                </Flex>
-              </Form.Item>
-            </Col>
-          </Row>
-          <Form.Item
-            style={{ marginBottom: 4 }}
-            label={
-              <Space direction="vertical" size={2} style={{ width: "100%" }}>
-                <Flex justify="space-between" align="center" gap={8} wrap={false}>
-                  <Space size={8} align="center" wrap>
-                    {labeledField(
-                      "settings.complex_fields.formula.columns.expression_json",
-                      "settings.complex_fields.formula.tooltips.expression_json",
-                    )}
-                    <Link style={{ fontSize: "0.85em" }} to="/help#formula-json-logic">
-                      {t("settings.complex_fields.help_links.formula_json")}
-                    </Link>
-                  </Space>
-                </Flex>
-                <Typography.Text type="secondary" style={{ minWidth: 0 }}>
-                  {t("settings.complex_fields.formula.expression_json_help")}
-                </Typography.Text>
-                <Typography.Text type="secondary" style={{ minWidth: 0 }}>
-                  {t("settings.complex_fields.formula.expression_json_example")}
-                </Typography.Text>
-              </Space>
-            }
-            name="expression_json"
-            trigger="onChange"
-            getValueFromEvent={(value: string) => value}
-            rules={[
-              {
-                validator: async (_, value) => {
-                  const parsed = parseExpressionJson(value);
-                  if (!parsed) {
-                    throw new Error(t("settings.complex_fields.formula.expression_json_required"));
-                  }
-                },
-              },
-            ]}
-          >
-            <div>
-              {isDesktopOperatorPanel && (
-                <Flex justify="flex-end" style={{ marginBottom: 2 }}>
-                  <Tooltip
-                    title={
-                      showInlineOperatorPanel
-                        ? t("settings.complex_fields.formula.json_builder.hide_operators")
-                        : t("settings.complex_fields.formula.json_builder.show_operators")
-                    }
-                  >
-                    <Button
-                      type="default"
-                      size="small"
-                      icon={showInlineOperatorPanel ? <MenuFoldOutlined /> : <MenuUnfoldOutlined />}
-                      onClick={() => setOperatorPanelCollapsed((current) => !current)}
-                      aria-label={
-                        showInlineOperatorPanel
-                          ? t("settings.complex_fields.formula.json_builder.hide_operators")
-                          : t("settings.complex_fields.formula.json_builder.show_operators")
-                      }
-                    />
-                  </Tooltip>
-                </Flex>
-              )}
-              <Flex align="stretch" gap={8} wrap={false}>
-                <div style={{ flex: 1, minWidth: 0 }}>
-                  <div
-                    style={{
-                      // Keep editor + operators visually balanced by default, while still allowing
-                      // manual vertical resize for longer JSON authoring sessions.
-                      height: showInlineOperatorPanel ? INLINE_OPERATOR_PANEL_HEIGHT : 196,
-                      minHeight: showInlineOperatorPanel ? INLINE_OPERATOR_PANEL_HEIGHT : 196,
-                      resize: "vertical",
-                      overflow: "auto",
-                    }}
-                  >
-                    <CodeMirror
-                      value={expressionJsonValue || ""}
-                      // Keep CodeMirror bound to the container height so dragging the resize handle
-                      // expands the visible editor instead of adding blank space below it.
-                      height="100%"
-                      style={{
-                        height: "100%",
-                        backgroundColor: token.colorBgContainer,
-                        color: token.colorText,
-                      }}
-                      extensions={[json(), drawSelection(), codeMirrorTheme]}
-                      basicSetup={{
-                        lineNumbers: true,
-                        drawSelection: false,
-                        // Keep standard editor affordances on and theme them via codeMirrorTheme.
-                        bracketMatching: true,
-                        highlightSelectionMatches: true,
-                        highlightActiveLine: false,
-                        foldGutter: true,
-                      }}
-                      onCreateEditor={(editor) => {
-                        expressionJsonEditorRef.current = editor;
-                        const mainSelection = editor.state.selection.main;
-                        expressionJsonSelectionRef.current = { from: mainSelection.from, to: mainSelection.to };
-                      }}
-                      onUpdate={(viewUpdate) => {
-                        const mainSelection = viewUpdate.state.selection.main;
-                        expressionJsonSelectionRef.current = { from: mainSelection.from, to: mainSelection.to };
-                      }}
-                      onChange={(value) => {
-                        derivedForm.setFieldValue("expression_json", value);
-                      }}
-                    />
-                  </div>
-                  <Flex justify="flex-end" style={{ marginTop: 4, marginRight: 18 }}>
-                    <Tooltip title={t("settings.complex_fields.formula.json_builder.format_tooltip")}>
-                      <Button size="small" onClick={() => formatExpressionJson()}>
-                        {t("settings.complex_fields.formula.json_builder.format")}
-                      </Button>
-                    </Tooltip>
-                  </Flex>
-                </div>
-                {showInlineOperatorPanel && (
-                  <div
-                    style={{
-                      width: OPERATOR_PANEL_WIDTH,
-                      flex: `0 0 ${OPERATOR_PANEL_WIDTH}px`,
-                      ...tokenPanelStyle,
-                      padding: 8,
-                      height: INLINE_OPERATOR_PANEL_HEIGHT,
-                      minHeight: INLINE_OPERATOR_PANEL_HEIGHT,
-                      overflowY: "auto",
-                    }}
-                  >
-                    <Typography.Text type="secondary" style={{ display: "block", textAlign: "right" }}>
-                      <strong>{t("settings.complex_fields.formula.token_sections.operators")}</strong>
-                    </Typography.Text>
-                    <div style={{ marginTop: 8 }}>{renderOperatorTokenGroups(true)}</div>
-                  </div>
-                )}
-              </Flex>
-            </div>
-          </Form.Item>
-          {/* Show helper/operators before references so helper-first insertion flow is visually guided. */}
-          <Space
-            direction="vertical"
-            size={2}
-            style={{
-              width: "100%",
-              marginBottom: 8,
-            }}
-          >
-            <Flex justify="space-between" align="center">
-              <Space size={8} align="center">
-                <Typography.Text type="secondary">
-                  <strong>{t("settings.complex_fields.formula.json_builder.operators_title")}</strong>
-                </Typography.Text>
-                <Link
-                  style={{ fontSize: "0.85em" }}
-                  to="/help#formula-token-groups"
-                >
-                  {t("settings.complex_fields.help_links.formula_tokens")}
-                </Link>
-              </Space>
-            </Flex>
-            <div style={tokenPanelStyle}>
-              <Space direction="vertical" size={8} style={{ width: "100%" }}>
-                <div>
-                  <Flex justify="space-between" align="center" gap={8} wrap={false} style={{ height: 34 }}>
-                    <Typography.Text type="secondary">
-                      <strong>{t("settings.complex_fields.formula.token_sections.helper_functions")}</strong>
-                    </Typography.Text>
-                    {pendingHelperHint ? (
-                      <Space size={6} style={{ minWidth: 0, flexShrink: 0 }}>
-                        <Typography.Text type="warning" style={{ whiteSpace: "nowrap" }}>
-                          {t("settings.complex_fields.formula.json_builder.pending_helper_prefix")}
-                        </Typography.Text>
-                        <Typography.Text code style={{ color: token.colorWarningText }}>
-                          {pendingHelperHint.helper}
-                        </Typography.Text>
-                        <Typography.Text type="warning" style={{ whiteSpace: "nowrap" }}>
-                          {t("settings.complex_fields.formula.json_builder.pending_helper_count", {
-                            selected: pendingHelperHint.selected,
-                            total: pendingHelperHint.total,
-                          })}
-                        </Typography.Text>
-                        <Tooltip title={t("settings.complex_fields.formula.json_builder.cancel_pending_tooltip")}>
-                          <Button
-                            danger
-                            size="small"
-                            type="text"
-                            icon={<CloseCircleOutlined />}
-                            onClick={() => cancelPendingHelperInsert()}
-                            aria-label={t("settings.complex_fields.formula.json_builder.cancel_pending_tooltip")}
-                          />
-                        </Tooltip>
-                        <Tooltip title={t("settings.complex_fields.formula.json_builder.insert_without_reference_tooltip")}>
-                          <Button
-                            size="small"
-                            type="primary"
-                            onClick={() => insertPendingHelperWithoutReferences()}
-                            aria-label={t("settings.complex_fields.formula.json_builder.insert_without_reference_tooltip")}
-                          >
-                            {t("settings.complex_fields.formula.json_builder.helper_only")}
-                          </Button>
-                        </Tooltip>
-                      </Space>
-                    ) : null}
-                  </Flex>
-                  <div style={{ marginTop: 6 }}>{renderHelperTokenGroups(true)}</div>
-                </div>
-                <div style={{ paddingTop: 4 }}>
-                  <Typography.Text type="secondary">
-                    <strong>{t("settings.complex_fields.formula.reference_picker.label")}</strong>
-                  </Typography.Text>
-                  <div style={{ ...tokenCategoryStyle, marginTop: 6 }}>
-                    <div style={referenceGridStyle}>
-                      {compactReferenceOptions.map((reference) => {
-                        const referenceCompatible = isReferenceCompatibleWithPendingHelper(reference.value);
-                        const isSelectedForPendingHelper = Boolean(
-                          pendingJsonHelperInsert?.selectedReferences.includes(reference.value),
-                        );
-                        const disabledReason =
-                          !referenceCompatible && pendingHelperDefinition
-                            ? t("settings.complex_fields.formula.json_builder.reference_incompatible_reason", {
-                                helper: pendingHelperDefinition.name,
-                              })
-                            : null;
-                        const referenceToken = (
-                          <Typography.Text
-                            code
-                            style={{
-                              cursor: disabledReason ? "not-allowed" : "pointer",
-                              opacity: disabledReason ? 0.45 : 1,
-                              whiteSpace: "nowrap",
-                              overflow: "hidden",
-                              textOverflow: "ellipsis",
-                              textAlign: "center",
-                              fontWeight: 500,
-                              color: isSelectedForPendingHelper
-                                ? token.colorPrimaryText
-                                : (!disabledReason && hoveredTokenId === `reference-${reference.value}` ? token.colorWarningText : undefined),
-                              background:
-                                !disabledReason && hoveredTokenId === `reference-${reference.value}` ? token.colorWarningBg : undefined,
-                              borderColor:
-                                !disabledReason && hoveredTokenId === `reference-${reference.value}`
-                                  ? token.colorWarningBorder
-                                  : undefined,
-                              transition: "all 120ms ease-out",
-                            }}
-                            onMouseEnter={!disabledReason ? () => setHoveredTokenId(`reference-${reference.value}`) : undefined}
-                            onMouseLeave={!disabledReason ? () => setHoveredTokenId((current) => (current === `reference-${reference.value}` ? null : current)) : undefined}
-                            onClick={!disabledReason ? () => insertExpressionJsonReference(reference.value) : undefined}
-                          >
-                            {reference.label}
-                          </Typography.Text>
-                        );
-                        // Keep a stable wrapper shape for all reference tokens so disabled/tooltip states
-                        // do not cause reflow when helper compatibility changes.
-                        const content = (
-                          <Tooltip title={disabledReason || undefined}>
-                            <span style={{ display: "inline-flex", justifyContent: "center" }}>{referenceToken}</span>
-                          </Tooltip>
-                        );
-                        return (
-                          <div
-                            key={`reference-cell-${reference.value}`}
-                            style={{ display: "flex", justifyContent: "center", alignItems: "center", minHeight: 24 }}
-                          >
-                            {content}
-                          </div>
-                        );
-                      })}
-                    </div>
-                  </div>
-                </div>
-              </Space>
-            </div>
-            <Typography.Paragraph type="secondary" style={{ marginBottom: 0 }}>
-              {t("settings.complex_fields.formula.json_builder.click_to_insert_help")}
-            </Typography.Paragraph>
-          </Space>
-          <Form.Item
-            label={labeledField(
-              "settings.complex_fields.formula.sample_values",
-              "settings.complex_fields.formula.tooltips.sample_values",
-            )}
-            name="sample_values"
-            extra={t("settings.complex_fields.formula.sample_values_help")}
-            rules={[
-              {
-                validator: async (_, value) => {
-                  parseSampleValues(value);
-                },
-              },
-            ]}
-          >
-            <Input.TextArea
-              autoSize={{ minRows: 3, maxRows: 6 }}
-              placeholder={sampleValuesPlaceholder}
-              style={{ fontFamily: token.fontFamilyCode || "monospace" }}
-            />
-          </Form.Item>
-          <Space
-            direction="vertical"
-            size="middle"
-            style={{
-              width: "100%",
-            }}
-          >
-            <Flex justify="space-between" align="center" wrap="wrap" gap={12}>
-              <Button onClick={() => previewDerived()} loading={previewDerivedField.isPending}>
-                {t("settings.complex_fields.formula.preview.button")}
-              </Button>
-              <Flex align="center" gap={8} style={{ marginLeft: "auto" }}>
-                {labeledField(
-                  "settings.complex_fields.formula.columns.include_in_api",
-                  "settings.complex_fields.formula.tooltips.include_in_api",
-                )}
-                <Form.Item name="include_in_api" valuePropName="checked" style={{ marginBottom: 0 }}>
-                  <Switch />
-                </Form.Item>
-              </Flex>
-            </Flex>
-            {previewSummary}
-          </Space>
-        </Form>
-      </Modal>
-      {contextHolder}
-    </>
-  );
-}
diff --git a/client/src/pages/settings/extraFieldsSettings.tsx b/client/src/pages/settings/extraFieldsSettings.tsx
index 7902b3e72..b8b12b62c 100644
--- a/client/src/pages/settings/extraFieldsSettings.tsx
+++ b/client/src/pages/settings/extraFieldsSettings.tsx
@@ -28,7 +28,7 @@ import { useParams } from "react-router";
 import { DateTimePicker } from "../../components/dateTimePicker";
 import { InputNumberRange } from "../../components/inputNumberRange";
 import { getExtraFieldReferences } from "../../utils/formulaFields";
-import { FormulaFieldsSettings } from "./complexFieldsSettings";
+import { FormulaFieldsSettings } from "./formulaFieldsSettings";
 import {
   EntityType,
   Field,
diff --git a/client/src/pages/settings/formulaFieldsSettings.tsx b/client/src/pages/settings/formulaFieldsSettings.tsx
new file mode 100644
index 000000000..952451e83
--- /dev/null
+++ b/client/src/pages/settings/formulaFieldsSettings.tsx
@@ -0,0 +1,2711 @@
+import { json } from "@codemirror/lang-json";
+import { HighlightStyle, syntaxHighlighting } from "@codemirror/language";
+import { EditorView, drawSelection } from "@codemirror/view";
+import CodeMirror from "@uiw/react-codemirror";
+import { tags as highlightTags } from "@lezer/highlight";
+import {
+  CloseCircleOutlined,
+  MenuFoldOutlined,
+  MenuUnfoldOutlined,
+  PlusOutlined,
+  QuestionCircleOutlined,
+  WarningOutlined,
+  CopyOutlined,
+} from "@ant-design/icons";
+import { useTranslate } from "@refinedev/core";
+import {
+  Button,
+  Checkbox,
+  Col,
+  Divider,
+  Empty,
+  Flex,
+  Form,
+  Grid,
+  Input,
+  Modal,
+  Popconfirm,
+  Row,
+  Space,
+  Switch,
+  Table,
+  Tag,
+  Tooltip,
+  Typography,
+  message,
+  theme,
+} from "antd";
+import { ColumnType } from "antd/es/table";
+import { type CSSProperties, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Link, useParams } from "react-router";
+import {
+  FORMULA_HELPER_GROUPS,
+  FORMULA_HELPERS,
+  FormulaHelperDefinition,
+  getExtraFieldReferences,
+  getFormulaReferencesFromJsonLogic,
+} from "../../utils/formulaFields";
+import {
+  FormulaFieldSurface,
+  DerivedField,
+  DerivedFieldType,
+  EntityType,
+  FieldType,
+  Field,
+  useDeleteDerivedField,
+  useGetDerivedFields,
+  useGetFields,
+  usePreviewDerivedField,
+  useSetDerivedField,
+} from "../../utils/queryFields";
+
+const BUILTIN_REFERENCE_SUGGESTIONS: Record<EntityType, string[]> = {
+  vendor: ["id", "name", "registered", "comment"],
+  filament: ["id", "name", "material", "price", "density", "weight", "color_hex", "comment", "registered"],
+  spool: ["id", "weight", "remaining_weight", "used_weight", "price", "lot_nr", "comment", "registered"],
+};
+const SAMPLE_VALUE_PLACEHOLDERS: Record<EntityType, string> = {
+  vendor: '{"name": "Example Vendor", "registered": "2026-02-28T10:15:00Z"}',
+  filament: '{"weight": 482.36, "material": "PLA", "registered": "2026-02-28T10:15:00Z", "color_hex": "#FF00FF"}',
+  spool: '{"weight": 482.36, "remaining_weight": 225.12, "registered": "2026-02-28T10:15:00Z"}',
+};
+const JSON_LOGIC_OPERATOR_GROUPS: Array<{ key: string; operators: string[] }> = [
+  { key: "logical", operators: ["if", "and", "or", "!"] },
+  { key: "comparison", operators: ["==", "!=", "<", "<=", ">", ">="] },
+  { key: "arithmetic", operators: ["+", "-", "*", "/", "%", "floor"] },
+];
+// Layout constants for consistent spacing and sizing.
+// OPERATOR_PANEL_WIDTH (244) and INLINE_OPERATOR_PANEL_HEIGHT (264) are paired to maintain
+// visual balance: the operator panel height matches the JSON editor height when operators show inline.
+// If adjusting one, keep them visually balanced so editor and operator box feel like one cohesive unit.
+const OPERATOR_PANEL_WIDTH = 244;
+const INLINE_OPERATOR_PANEL_HEIGHT = 264;
+// Keep helper groups dense on desktop by pairing short groups under larger ones.
+const HELPER_DESKTOP_COLUMN_LAYOUT: Array<{ top: string; bottom?: string }> = [
+  { top: "math", bottom: "color" },
+  { top: "text" },
+  { top: "datetime" },
+  { top: "dynamic", bottom: "date_diff" },
+];
+const JSON_LOGIC_OPERATOR_SNIPPETS: Record<string, string> = {
+  if: '{\n  "if": [\n    {"var": "condition"},\n    "then_value",\n    "else_value"\n  ]\n}',
+  and: '{\n  "and": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  or: '{\n  "or": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "!": '{\n  "!": [\n    {"var": "value"}\n  ]\n}',
+  "==": '{\n  "==": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "!=": '{\n  "!=": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "<": '{\n  "<": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "<=": '{\n  "<=": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  ">": '{\n  ">": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  ">=": '{\n  ">=": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "+": '{\n  "+": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "-": '{\n  "-": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "*": '{\n  "*": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "/": '{\n  "/": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  "%": '{\n  "%": [\n    {"var": "left"},\n    {"var": "right"}\n  ]\n}',
+  floor: '{\n  "floor": [\n    {"var": "value"}\n  ]\n}',
+};
+const JSON_LOGIC_OPERATOR_OPERAND_COUNTS: Record<string, number> = {
+  if: 3,
+  and: 2,
+  or: 2,
+  "!": 1,
+  "==": 2,
+  "!=": 2,
+  "<": 2,
+  "<=": 2,
+  ">": 2,
+  ">=": 2,
+  "+": 2,
+  "-": 2,
+  "*": 2,
+  "/": 2,
+  "%": 2,
+  floor: 1,
+};
+// IF guided mode narrows the condition-builder to explicit comparison operators only.
+const IF_CONDITION_COMPARISON_OPERATORS = new Set(["==", "!=", "<", "<=", ">", ">="]);
+// Default scaffold shown immediately when IF is clicked on an empty editor.
+const IF_SCAFFOLD_SNIPPET = '{\n  "if": [\n    {\n      "Condition": []\n    },\n    "Then",\n    "Else"\n  ]\n}';
+const RESERVED_DERIVED_KEY_NAMES = new Set([
+  ...JSON_LOGIC_OPERATOR_GROUPS.flatMap((group) => group.operators),
+  ...FORMULA_HELPERS.map((helper) => helper.name),
+]);
+
+type ReferenceValueKind = "any" | "number" | "datetime" | "text" | "boolean" | "range" | "unknown";
+type PendingHelperOperand = { kind: "reference"; value: string } | { kind: "helper"; value: string };
+type PendingOperatorInsertState = {
+  operator: string;
+  selectedOperands: unknown[];
+  requiredOperandCount: number;
+  // `if` can optionally guide users through a structured condition:
+  // compare operator -> left operand -> right operand -> then -> else.
+  pendingIfComparisonOperator?: string | null;
+  pendingIfComparisonOperands?: unknown[];
+  replaceEditorOnComplete?: boolean;
+};
+type PendingHelperInsertState = {
+  helperName: string;
+  selectedOperands: PendingHelperOperand[];
+};
+type PendingHelperHintState = {
+  helper: string;
+  selected: number;
+  total: number;
+  allowHelperOnly: boolean;
+  stepLabelKey?: string;
+};
+type FormulaResultTypeHint = "number" | "text" | "boolean" | "unknown";
+
+// Resolve the current IF guided-insert prompt step so the yellow helper hint can
+// explicitly tell users what token click is expected next.
+function getIfPendingStepLabelKey(state: PendingOperatorInsertState): string {
+  if (state.selectedOperands.length === 0) {
+    if (!state.pendingIfComparisonOperator) {
+      return "settings.formula_fields.formula.json_builder.if_step_condition_operator";
+    }
+    const comparisonOperandCount = state.pendingIfComparisonOperands?.length || 0;
+    if (comparisonOperandCount === 0) {
+      return "settings.formula_fields.formula.json_builder.if_step_condition_left";
+    }
+    return "settings.formula_fields.formula.json_builder.if_step_condition_right";
+  }
+  if (state.selectedOperands.length === 1) {
+    return "settings.formula_fields.formula.json_builder.if_step_then";
+  }
+  return "settings.formula_fields.formula.json_builder.if_step_else";
+}
+
+const BUILTIN_REFERENCE_KIND_HINTS: Record<EntityType, Record<string, ReferenceValueKind>> = {
+  vendor: {
+    id: "number",
+    name: "text",
+    registered: "datetime",
+    comment: "text",
+  },
+  filament: {
+    id: "number",
+    name: "text",
+    material: "text",
+    price: "number",
+    density: "number",
+    weight: "number",
+    color_hex: "text",
+    comment: "text",
+    registered: "datetime",
+    created_at: "datetime",
+  },
+  spool: {
+    id: "number",
+    weight: "number",
+    remaining_weight: "number",
+    used_weight: "number",
+    price: "number",
+    lot_nr: "text",
+    comment: "text",
+    registered: "datetime",
+    created_at: "datetime",
+  },
+};
+
+function resolveColorLuminance(color: string): number | null {
+  const normalized = color.trim().toLowerCase();
+
+  const hexMatch = normalized.match(/^#([a-f0-9]{3,4}|[a-f0-9]{6}|[a-f0-9]{8})$/);
+  if (hexMatch) {
+    const hex = hexMatch[1];
+    const value =
+      hex.length === 3 || hex.length === 4
+        ? `${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}`
+        : hex.slice(0, 6);
+    const r = parseInt(value.slice(0, 2), 16);
+    const g = parseInt(value.slice(2, 4), 16);
+    const b = parseInt(value.slice(4, 6), 16);
+    return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+  }
+
+  const rgbMatch = normalized.match(/^rgba?\(([^)]+)\)$/);
+  if (!rgbMatch) {
+    return null;
+  }
+  const channels = rgbMatch[1]
+    .split(",")
+    .map((part) => part.trim())
+    .slice(0, 3);
+  if (channels.length !== 3) {
+    return null;
+  }
+
+  const toByte = (channel: string): number | null => {
+    if (channel.endsWith("%")) {
+      const percent = Number(channel.slice(0, -1));
+      if (Number.isNaN(percent)) {
+        return null;
+      }
+      return Math.round((Math.max(0, Math.min(100, percent)) / 100) * 255);
+    }
+    const value = Number(channel);
+    if (Number.isNaN(value)) {
+      return null;
+    }
+    return Math.max(0, Math.min(255, value));
+  };
+
+  const r = toByte(channels[0]);
+  const g = toByte(channels[1]);
+  const b = toByte(channels[2]);
+  if (r == null || g == null || b == null) {
+    return null;
+  }
+  return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+}
+
+function formatPreviewValue(value: string | number | boolean | null): string {
+  if (value === null) {
+    return "null";
+  }
+  return `${value}`;
+}
+
+// Validates and parses sample values JSON. Called during form validation.
+// Throws localized error message if JSON is invalid (not an object).
+function parseSampleValues(raw: string | undefined, errorTranslation?: string): Record<string, unknown> {
+  if (!raw || raw.trim() === "") {
+    return {};
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+      throw new Error(errorTranslation || "Sample values must be a JSON object.");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (e) {
+    if (e instanceof Error && (e.message === errorTranslation || !errorTranslation)) {
+      throw e;
+    }
+    // If JSON.parse failed, throw the user-friendly error
+    throw new Error(errorTranslation || "Sample values must be a JSON object.");
+  }
+}
+
+// Validates and parses expression JSON. Called during form validation.
+// Returns undefined if empty, throws localized error if invalid.
+function parseExpressionJson(raw: string | undefined, errorTranslation?: string): Record<string, unknown> | undefined {
+  if (!raw || raw.trim() === "") {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+      throw new Error(errorTranslation || "Expression JSON must be a JSON object.");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (e) {
+    if (e instanceof Error && (e.message === errorTranslation || !errorTranslation)) {
+      throw e;
+    }
+    // If JSON.parse failed, throw the user-friendly error
+    throw new Error(errorTranslation || "Expression JSON must be a JSON object.");
+  }
+}
+
+function hasReferencePath(sampleValues: Record<string, unknown>, reference: string): boolean {
+  const parts = reference.split(".").filter((part) => part.length > 0);
+  if (parts.length === 0) {
+    return false;
+  }
+
+  let current: unknown = sampleValues;
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index];
+    if (current === null || typeof current !== "object" || Array.isArray(current)) {
+      return false;
+    }
+    const record = current as Record<string, unknown>;
+    if (!(part in record)) {
+      return false;
+    }
+    current = record[part];
+  }
+
+  return true;
+}
+
+// Ensure every detected reference path exists in sample JSON so preview can evaluate formulas
+// immediately without requiring the user to hand-create nested keys.
+function insertReferencePathIfMissing(
+  sampleValues: Record<string, unknown>,
+  reference: string,
+  defaultValue: unknown,
+): boolean {
+  const parts = reference.split(".").filter((part) => part.length > 0);
+  if (parts.length === 0) {
+    return false;
+  }
+
+  let current: Record<string, unknown> = sampleValues;
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    const part = parts[index];
+    const existing = current[part];
+    if (existing === undefined) {
+      current[part] = {};
+      current = current[part] as Record<string, unknown>;
+      continue;
+    }
+    if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
+      return false;
+    }
+    current = existing as Record<string, unknown>;
+  }
+
+  const leaf = parts[parts.length - 1];
+  if (leaf in current) {
+    return false;
+  }
+  current[leaf] = defaultValue;
+  return true;
+}
+
+// Remove a previously auto-managed reference path when it no longer appears in the expression.
+// This keeps sample JSON aligned with active refs and prunes empty parent objects afterwards.
+function removeReferencePathIfPresent(sampleValues: Record<string, unknown>, reference: string): boolean {
+  const parts = reference.split(".").filter((part) => part.length > 0);
+  if (parts.length === 0) {
+    return false;
+  }
+
+  const parents: Array<{ record: Record<string, unknown>; key: string }> = [];
+  let current: Record<string, unknown> = sampleValues;
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    const part = parts[index];
+    const nextValue = current[part];
+    if (nextValue === null || typeof nextValue !== "object" || Array.isArray(nextValue)) {
+      return false;
+    }
+    parents.push({ record: current, key: part });
+    current = nextValue as Record<string, unknown>;
+  }
+
+  const leaf = parts[parts.length - 1];
+  if (!(leaf in current)) {
+    return false;
+  }
+  delete current[leaf];
+
+  // Remove now-empty containers so deleted transient references do not leave dead paths behind.
+  for (let index = parents.length - 1; index >= 0; index -= 1) {
+    const { record, key } = parents[index];
+    const value = record[key];
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      break;
+    }
+    if (Object.keys(value as Record<string, unknown>).length > 0) {
+      break;
+    }
+    delete record[key];
+  }
+  return true;
+}
+
+// Use bounded random numeric defaults so auto-scaffolded sample values feel realistic
+// and avoid repeating the same constant during expression authoring.
+function randomIntegerSampleValue(): number {
+  return Math.floor(Math.random() * 1001);
+}
+
+function randomFloatSampleValue(): number {
+  return Number((Math.random() * 1000).toFixed(2));
+}
+
+// Randomize datetime sample times so date-diff previews surface fractional values by default.
+function randomTwoDigitSampleValue(maxExclusive: number): string {
+  return Math.floor(Math.random() * maxExclusive).toString().padStart(2, "0");
+}
+
+function randomIsoDatetimeSampleValue(baseDate: string): string {
+  return baseDate + "T" + randomTwoDigitSampleValue(24) + ":" + randomTwoDigitSampleValue(60) + ":" + randomTwoDigitSampleValue(60) + "Z";
+}
+
+function randomOrderedIntegerRangeSampleValue(): [number, number] {
+  const first = randomIntegerSampleValue();
+  const second = randomIntegerSampleValue();
+  return first <= second ? [first, second] : [second, first];
+}
+
+function randomOrderedFloatRangeSampleValue(): [number, number] {
+  const first = randomFloatSampleValue();
+  const second = randomFloatSampleValue();
+  return first <= second ? [first, second] : [second, first];
+}
+
+function getSampleDefaultValue(kind: ReferenceValueKind, reference: string, configuredField?: Field): unknown {
+  // Custom extra-field defaults are type-driven so newly referenced fields get
+  // meaningful sample values immediately for preview runs.
+  if (configuredField) {
+    switch (configuredField.field_type) {
+      case FieldType.text:
+        return "Preview Text";
+      case FieldType.integer:
+        return randomIntegerSampleValue();
+      case FieldType.integer_range:
+        return randomOrderedIntegerRangeSampleValue();
+      case FieldType.float:
+        return randomFloatSampleValue();
+      case FieldType.float_range:
+        return randomOrderedFloatRangeSampleValue();
+      case FieldType.datetime:
+        // ISO format preserves the user-requested timestamp/CET intent while remaining parser-safe.
+        return randomIsoDatetimeSampleValue("2019-05-01");
+      case FieldType.boolean:
+        return true;
+      case FieldType.choice:
+        if (configuredField.multi_choice) {
+          return configuredField.choices?.slice(0, 2) ?? ["Spool", "Man"];
+        }
+        return configuredField.choices?.[0] ?? "Spool";
+      default:
+        return null;
+    }
+  }
+
+  const referenceLeaf = reference.split(".").filter(Boolean).at(-1) || reference;
+  const normalizedLeaf = referenceLeaf.toLowerCase();
+
+  // Seed known semantic fields with practical defaults so preview works immediately
+  // without forcing users to hand-craft first-pass sample values.
+  if (normalizedLeaf.includes("color_hex") || normalizedLeaf.endsWith("_hex")) {
+    return "#FF00FF";
+  }
+
+  switch (kind) {
+    case "number":
+      return randomFloatSampleValue();
+    case "boolean":
+      return false;
+    case "datetime":
+      return randomIsoDatetimeSampleValue("2026-01-01");
+    case "text":
+      return "sample_text";
+    case "range":
+      return randomOrderedFloatRangeSampleValue();
+    default:
+      return null;
+  }
+}
+
+function mergeTypeHints(typeHints: FormulaResultTypeHint[]): FormulaResultTypeHint {
+  const knownHints = typeHints.filter((typeHint) => typeHint !== "unknown");
+  if (knownHints.length === 0) {
+    return "unknown";
+  }
+  return knownHints.every((typeHint) => typeHint === knownHints[0]) ? knownHints[0] : "unknown";
+}
+
+function inferExpressionJsonType(node: unknown): FormulaResultTypeHint {
+  if (typeof node === "number") {
+    return "number";
+  }
+  if (typeof node === "string") {
+    return "text";
+  }
+  if (typeof node === "boolean") {
+    return "boolean";
+  }
+  if (node === null || Array.isArray(node) || typeof node !== "object") {
+    return "unknown";
+  }
+
+  const entries = Object.entries(node as Record<string, unknown>);
+  if (entries.length !== 1) {
+    return "unknown";
+  }
+
+  const [operator, rawArgs] = entries[0];
+  const args = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+
+  if (operator === "var") {
+    return "unknown";
+  }
+
+  if (operator === "if") {
+    const branchHints: FormulaResultTypeHint[] = [];
+    for (let index = 1; index < args.length; index += 2) {
+      branchHints.push(inferExpressionJsonType(args[index]));
+    }
+    if (args.length % 2 === 0 && args.length > 0) {
+      branchHints.push(inferExpressionJsonType(args[args.length - 1]));
+    }
+    return mergeTypeHints(branchHints);
+  }
+
+  if (operator === "coalesce") {
+    return mergeTypeHints(args.map((arg) => inferExpressionJsonType(arg)));
+  }
+
+  if (["==", "!=", "<", "<=", ">", ">=", "!", "and", "or"].includes(operator)) {
+    return "boolean";
+  }
+
+  if (
+    [
+      "+",
+      "-",
+      "*",
+      "/",
+      "%",
+      "abs",
+      "min",
+      "max",
+      "round",
+      "year",
+      "month",
+      "day",
+      "hour",
+      "minute",
+      "second",
+      "timestamp",
+      "days_between",
+      "hours_between",
+      "hue_from_hex",
+      "length",
+    ].includes(operator)
+  ) {
+    return "number";
+  }
+
+  if (["date_only", "time_only", "today", "cat", "concat", "replace", "trim", "upper", "lower", "left", "right"].includes(operator)) {
+    return "text";
+  }
+
+  return "unknown";
+}
+
+function toDerivedFieldType(typeHint: FormulaResultTypeHint): DerivedFieldType | null {
+  if (typeHint === "number") {
+    return DerivedFieldType.number;
+  }
+  if (typeHint === "text") {
+    return DerivedFieldType.text;
+  }
+  return null;
+}
+
+export function FormulaFieldsSettings() {
+  const { entityType } = useParams<{ entityType: EntityType }>();
+  const t = useTranslate();
+  const { token } = theme.useToken();
+  const screens = Grid.useBreakpoint();
+  const [messageApi, contextHolder] = message.useMessage();
+  const [derivedModalOpen, setDerivedModalOpen] = useState(false);
+  const [editingDerivedKey, setEditingDerivedKey] = useState<string | null>(null);
+  const [previewText, setPreviewText] = useState<string | null>(null);
+  const [previewErrorText, setPreviewErrorText] = useState<string | null>(null);
+  const [pendingJsonHelperInsert, setPendingJsonHelperInsert] = useState<PendingHelperInsertState | null>(null);
+  const [pendingOperatorInsert, setPendingOperatorInsert] = useState<PendingOperatorInsertState | null>(null);
+  const [operatorPanelCollapsed, setOperatorPanelCollapsed] = useState(false);
+  const [tokensPanelCollapsed, setTokensPanelCollapsed] = useState(false);
+  const [hoveredTokenId, setHoveredTokenId] = useState<string | null>(null);
+  const [sampleValuesAutoUpdateEnabled, setSampleValuesAutoUpdateEnabled] = useState(true);
+  const [derivedForm] = Form.useForm();
+  const expressionJsonEditorRef = useRef<EditorView | null>(null);
+  const expressionJsonSelectionRef = useRef<{ from: number; to: number }>({ from: 0, to: 0 });
+  const expressionJsonProgrammaticValueRef = useRef<string | null>(null);
+  const previewRequestRef = useRef(0);
+  // Track only auto-scaffolded sample references so we can safely prune stale transient
+  // keys without deleting user-authored sample keys.
+  const autoManagedSampleReferencesRef = useRef<Set<string>>(new Set());
+
+  const selectedEntityType = entityType as EntityType;
+  const niceName = t(`${selectedEntityType}.${selectedEntityType}`);
+  const sectionBodyStyle = { marginTop: 0, fontSize: token.fontSize, lineHeight: 1.7 };
+  const tokenPanelStyle = useMemo(
+    () => ({
+      border: `1px solid ${token.colorBorderSecondary}`,
+      borderRadius: token.borderRadiusLG,
+      padding: 10,
+      background: token.colorBgContainer,
+    }),
+    [token.colorBgContainer, token.colorBorderSecondary, token.borderRadiusLG],
+  );
+  const tokenCategoryStyle = useMemo(
+    () => ({
+      borderRadius: token.borderRadius,
+      border: `1px solid ${token.colorBorderSecondary}`,
+      background: token.colorFillQuaternary,
+      padding: "8px 10px",
+      minHeight: 68,
+    }),
+    [token.borderRadius, token.colorBorderSecondary, token.colorFillQuaternary],
+  );
+  const tokenListStyle = useMemo<CSSProperties>(
+    () => ({
+      display: "flex",
+      flexWrap: "wrap",
+      gap: 6,
+      marginTop: 6,
+      justifyContent: "center",
+    }),
+    [],
+  );
+  const compactHelperCategoryStyle = useMemo<CSSProperties>(
+    () => ({
+      padding: "6px",
+      minHeight: 52,
+    }),
+    [],
+  );
+  const compactHelperTokenListStyle = useMemo<CSSProperties>(
+    () => ({
+      ...tokenListStyle,
+      justifyContent: "center",
+      marginTop: 4,
+      gap: 4,
+    }),
+    [tokenListStyle],
+  );
+  const referenceGridStyle = useMemo(
+    () => ({
+      display: "grid",
+      // Keep references dense while predictable: 4 columns on desktop, 3/2 on medium widths, 1 on mobile.
+      gridTemplateColumns: screens.lg || screens.xl || screens.xxl
+        ? "repeat(4, minmax(0, 1fr))"
+        : screens.md
+          ? "repeat(3, minmax(0, 1fr))"
+          : screens.sm
+            ? "repeat(2, minmax(0, 1fr))"
+            : "repeat(1, minmax(0, 1fr))",
+      gap: 6,
+    }),
+    [screens.lg, screens.md, screens.sm, screens.xl, screens.xxl],
+  );
+  const isDesktopLayout = Boolean(screens.lg || screens.xl || screens.xxl);
+  const isDesktopOperatorPanel = isDesktopLayout;
+  const showInlineOperatorPanel = Boolean(isDesktopOperatorPanel && !operatorPanelCollapsed);
+  const expressionEditorHeight = INLINE_OPERATOR_PANEL_HEIGHT;
+  // Keep JSON string tokens orange in both editors so references/values do not appear as errors.
+  const codeMirrorHighlightStyle = useMemo(
+    () =>
+      HighlightStyle.define([
+        {
+          tag: [highlightTags.string, highlightTags.special(highlightTags.string)],
+          color: token.colorWarningText,
+        },
+      ]),
+    [token.colorWarningText],
+  );
+  const codeMirrorSyntaxHighlight = useMemo(
+    () => syntaxHighlighting(codeMirrorHighlightStyle),
+    [codeMirrorHighlightStyle],
+  );
+  const codeMirrorTheme = useMemo(() => {
+    const bgLuminance = resolveColorLuminance(token.colorBgContainer);
+    const textLuminance = resolveColorLuminance(token.colorText);
+    const isDark = bgLuminance != null ? bgLuminance < 0.5 : (textLuminance ?? 0) > 0.6;
+    // Use Ant warning background tokens so selection follows the theme palette,
+    // but stays muted enough for multiline editing in dark mode.
+    const selectionColor = isDark ? token.colorWarningBg : token.colorWarningBgHover;
+    const selectionMatchColor = isDark ? "rgba(250, 173, 20, 0.24)" : "rgba(250, 173, 20, 0.18)";
+    const activeLineColor = isDark ? "rgba(250, 173, 20, 0.02)" : "rgba(22, 119, 255, 0.04)";
+    const activeLineGutterColor = isDark ? "rgba(250, 173, 20, 0.04)" : "rgba(22, 119, 255, 0.06)";
+    // Force editor foreground/background directly from design tokens so formula JSON remains
+    // readable in both light and dark themes regardless of global CSS inheritance.
+    return EditorView.theme(
+      {
+        "&": {
+          backgroundColor: token.colorBgContainer,
+          color: token.colorText,
+          borderRadius: token.borderRadius,
+          border: `1px solid ${token.colorBorder}`,
+        },
+        "&.cm-editor": {
+          backgroundColor: token.colorBgContainer,
+          color: token.colorText,
+        },
+        "& .cm-scroller": {
+          backgroundColor: token.colorBgContainer,
+          color: token.colorText,
+        },
+        "&.cm-focused": {
+          outline: `1px solid ${token.colorPrimaryBorderHover}`,
+        },
+        ".cm-scroller": {
+          fontFamily: token.fontFamilyCode || "monospace",
+        },
+        ".cm-content, .cm-line": {
+          color: token.colorText,
+          caretColor: token.colorText,
+        },
+        // Keep JSON string literals in warning/orange instead of red so valid string values
+        // don't read like errors in either expression or sample-value editors.
+        ".cm-string": {
+          color: `${token.colorWarningText} !important`,
+        },
+        ".cm-cursor, .cm-dropCursor": {
+          borderLeftColor: token.colorText,
+        },
+        // Keep bracket feedback enabled (standard editor behavior) but align it to amber theme.
+        ".cm-matchingBracket": {
+          backgroundColor: `${selectionMatchColor} !important`,
+          color: token.colorText,
+          outline: `1px solid ${token.colorWarningBorder}`,
+          borderRadius: 2,
+        },
+        ".cm-nonmatchingBracket": {
+          backgroundColor: "transparent !important",
+          color: token.colorError,
+          outline: `1px solid ${token.colorErrorBorder}`,
+          borderRadius: 2,
+        },
+        // Keep selection/search matches enabled (standard behavior), but use the same amber family.
+        ".cm-content .cm-selectionMatch, .cm-content .cm-searchMatch, .cm-content .cm-searchMatch-selected": {
+          backgroundColor: `${selectionMatchColor} !important`,
+          outline: `1px solid ${token.colorWarningBorder}`,
+          border: "none !important",
+          borderRadius: 2,
+          boxShadow: "none !important",
+        },
+        ".cm-gutters": {
+          backgroundColor: token.colorBgElevated,
+          color: token.colorTextTertiary,
+          borderRight: `1px solid ${token.colorBorderSecondary}`,
+        },
+        ".cm-activeLine": {
+          backgroundColor: activeLineColor,
+        },
+        ".cm-activeLineGutter": {
+          backgroundColor: activeLineGutterColor,
+        },
+        ".cm-selectionLayer": {
+          mixBlendMode: "normal",
+        },
+        // Force one consistent drawn selection color for both focused and blurred states.
+        ".cm-selectionBackground, .cm-selectionLayer .cm-selectionBackground, &.cm-focused .cm-selectionBackground, &.cm-focused .cm-selectionLayer .cm-selectionBackground": {
+          backgroundColor: `${selectionColor} !important`,
+          borderRadius: 2,
+        },
+        // Keep native browser selection transparent so it doesn't override with platform colors.
+        ".cm-content ::selection, .cm-line ::selection, .cm-line > span::selection, .cm-content *::selection": {
+          backgroundColor: "transparent !important",
+        },
+      },
+      { dark: isDark },
+    );
+  }, [
+    token.borderRadius,
+    token.colorBgContainer,
+    token.colorBgElevated,
+    token.colorBorder,
+    token.colorBorderSecondary,
+    token.colorError,
+    token.colorErrorBorder,
+    token.colorPrimaryBorderHover,
+    token.colorText,
+    token.colorTextTertiary,
+    token.colorWarningBorder,
+    token.colorWarningBg,
+    token.colorWarningBgHover,
+    token.fontFamilyCode,
+  ]);
+  const derivedFields = useGetDerivedFields(selectedEntityType);
+  const configuredFields = useGetFields(selectedEntityType);
+  const setDerivedField = useSetDerivedField(selectedEntityType);
+  const deleteDerivedField = useDeleteDerivedField(selectedEntityType);
+  const previewDerivedField = usePreviewDerivedField(selectedEntityType);
+  const expressionJsonValue = Form.useWatch("expression_json", derivedForm) as string | undefined;
+  const sampleValuesValue = Form.useWatch("sample_values", derivedForm) as string | undefined;
+  const derivedKeyValue = ((Form.useWatch("key", derivedForm) as string | undefined) || "").trim();
+  // Show the concrete API/template path for the currently typed key to remove
+  // ambiguity between formula operator names and field output identifiers.
+  const derivedKeyPath = useMemo(
+    () => (derivedKeyValue ? `derived.${derivedKeyValue}` : "derived.<key>"),
+    [derivedKeyValue],
+  );
+  const displaySurfaceOptions = useMemo(
+    () => [
+      { value: FormulaFieldSurface.show, label: t("settings.formula_fields.formula.display_targets.show_pages") },
+      {
+        value: FormulaFieldSurface.template,
+        label: t("settings.formula_fields.formula.display_targets.template_selections"),
+      },
+      { value: FormulaFieldSurface.list, label: t("settings.formula_fields.formula.display_targets.tables") },
+    ],
+    [t],
+  );
+  const keyLooksLikeReservedToken = useMemo(
+    () => RESERVED_DERIVED_KEY_NAMES.has(derivedKeyValue),
+    [derivedKeyValue],
+  );
+
+  const sampleValuesPlaceholder = SAMPLE_VALUE_PLACEHOLDERS[selectedEntityType];
+
+  const labeledField = (labelKey: string, tooltipKey: string) => (
+    <Space size={4}>
+      <span>{t(labelKey)}</span>
+      <Tooltip title={t(tooltipKey)}>
+        <QuestionCircleOutlined />
+      </Tooltip>
+    </Space>
+  );
+
+  const referenceOptions = useMemo(() => {
+    const extraReferences = (configuredFields.data || []).map((field) => `extra.${field.key}`);
+    // Suggest both built-in fields and configured extra fields so users can compose formulas
+    // without memorizing the exact reference syntax for each entity.
+    return [...new Set([...BUILTIN_REFERENCE_SUGGESTIONS[selectedEntityType], ...extraReferences])];
+  }, [configuredFields.data, selectedEntityType]);
+  const configuredFieldByReference = useMemo(
+    () =>
+      Object.fromEntries(
+        (configuredFields.data || []).map((field) => [`extra.${field.key}`, field] as const),
+      ) as Record<string, Field>,
+    [configuredFields.data],
+  );
+  const compactReferenceOptions = useMemo(
+    () =>
+      referenceOptions.map((reference) => ({
+        value: reference,
+        label: `{${reference}}`,
+      })),
+    [referenceOptions],
+  );
+  // Keep parsed expression state explicit so reference syncing only mutates sample JSON
+  // when the editor content is valid JSON (invalid typing states should not generate keys).
+  const parsedExpressionJson = useMemo(() => {
+    try {
+      return parseExpressionJson(expressionJsonValue);
+    } catch {
+      return null;
+    }
+  }, [expressionJsonValue]);
+
+  // Detect active var references from the current valid expression only.
+  const detectedExpressionReferences = useMemo(() => {
+    if (!parsedExpressionJson) {
+      return [] as string[];
+    }
+    return getFormulaReferencesFromJsonLogic(parsedExpressionJson).filter((reference) => reference.trim().length > 0);
+  }, [parsedExpressionJson]);
+  const parsedSampleValues = useMemo(() => {
+    try {
+      return parseSampleValues(sampleValuesValue);
+    } catch {
+      return null;
+    }
+  }, [sampleValuesValue]);
+  const missingSampleValueReferences = useMemo(() => {
+    if (!parsedSampleValues) {
+      return [] as string[];
+    }
+    return detectedExpressionReferences.filter((reference) => !hasReferencePath(parsedSampleValues, reference));
+  }, [detectedExpressionReferences, parsedSampleValues]);
+  const hasValidSampleValues = parsedSampleValues !== null;
+  const helperByName = useMemo(
+    () => Object.fromEntries(FORMULA_HELPERS.map((helper) => [helper.name, helper] as const)),
+    [],
+  );
+  const operatorGroups = useMemo(
+    () =>
+      JSON_LOGIC_OPERATOR_GROUPS.map((group) => ({
+        ...group,
+        label: t(`settings.formula_fields.formula.token_categories.${group.key}`),
+      })),
+    [t],
+  );
+  const helperGroups = useMemo(
+    () =>
+      FORMULA_HELPER_GROUPS.map((group) => ({
+        ...group,
+        label: t(`settings.formula_fields.formula.token_categories.${group.key}`),
+      })),
+    [t],
+  );
+  const helperGroupByKey = useMemo(
+    () => Object.fromEntries(helperGroups.map((group) => [group.key, group])),
+    [helperGroups],
+  );
+  const referenceKindByName = useMemo(() => {
+    const map: Record<string, ReferenceValueKind> = {
+      ...BUILTIN_REFERENCE_KIND_HINTS[selectedEntityType],
+    };
+
+    (configuredFields.data || []).forEach((field) => {
+      const fieldKind: ReferenceValueKind = (() => {
+        switch (field.field_type) {
+          case FieldType.integer:
+          case FieldType.float:
+            return "number";
+          case FieldType.datetime:
+            return "datetime";
+          case FieldType.boolean:
+            return "boolean";
+          case FieldType.integer_range:
+          case FieldType.float_range:
+            return "range";
+          case FieldType.text:
+          case FieldType.choice:
+            return "text";
+          default:
+            return "unknown";
+        }
+      })();
+      map[`extra.${field.key}`] = fieldKind;
+    });
+
+    return map;
+  }, [configuredFields.data, selectedEntityType]);
+  const getHelperReferenceCount = (helper: FormulaHelperDefinition): number => {
+    if (helper.insert_mode === "none") {
+      return 0;
+    }
+    return helper.reference_count ?? 1;
+  };
+  // Resolve how many operands an operator requires so the click-flow can collect
+  // references/helpers and insert complete JSON Logic snippets in one step.
+  const getOperatorOperandCount = (operator: string): number => {
+    return JSON_LOGIC_OPERATOR_OPERAND_COUNTS[operator] ?? 2;
+  };
+  // `if` guided mode starts by collecting a comparison operator for the condition node.
+  const isAwaitingIfComparisonOperator = useMemo(
+    () =>
+      pendingOperatorInsert?.operator === "if" &&
+      pendingOperatorInsert.selectedOperands.length === 0 &&
+      !pendingOperatorInsert.pendingIfComparisonOperator,
+    [pendingOperatorInsert],
+  );
+  // While `if` is waiting for a comparison operator, shade out non-comparison operator tokens
+  // so click-flow remains deterministic and users are guided toward valid condition structure.
+  const isOperatorTokenTemporarilyDisabled = (operator: string): boolean => {
+    if (!isAwaitingIfComparisonOperator) {
+      return false;
+    }
+    return !IF_CONDITION_COMPARISON_OPERATORS.has(operator);
+  };
+  const helperAllowsReferenceKind = (helper: FormulaHelperDefinition, referenceKind: ReferenceValueKind): boolean => {
+    const requiredKind = helper.reference_kind ?? "any";
+    if (requiredKind === "any") {
+      return true;
+    }
+    return referenceKind === requiredKind;
+  };
+  const pendingHelperDefinition = useMemo(() => {
+    if (!pendingJsonHelperInsert) {
+      return null;
+    }
+    return helperByName[pendingJsonHelperInsert.helperName] || null;
+  }, [helperByName, pendingJsonHelperInsert]);
+  const getHelperDisabledReason = (helper: FormulaHelperDefinition): string | null => {
+    // Keep date-diff pending mode intentionally narrow: only today() may act as the helper-side
+    // operand while reference picking handles datetime fields like created_at/extra.dry_date.
+    if (pendingHelperDefinition?.category === "date_diff" && helper.name !== "today") {
+      return t("settings.formula_fields.formula.json_builder.helper_incompatible_reason", { helper: helper.name });
+    }
+
+    if (helper.insert_mode === "none") {
+      return null;
+    }
+
+    const requiredRefCount = getHelperReferenceCount(helper);
+    const compatibleReferences = referenceOptions.filter((reference) =>
+      helperAllowsReferenceKind(helper, referenceKindByName[reference] || "unknown"),
+    );
+    // Date-diff helpers can still be composed with non-reference operands (for example today()),
+    // so keep them available even when matching reference count is below required placeholders.
+    const supportsNonReferenceOperands = helper.category === "date_diff";
+    if (!supportsNonReferenceOperands && compatibleReferences.length < requiredRefCount) {
+      return t("settings.formula_fields.formula.json_builder.helper_unavailable_reason", { helper: helper.name });
+    }
+
+    // When the user already picked reference #1 for a pending helper, temporarily disable helper
+    // tokens that can't accept that selected reference kind. Clearing/completing pending insert
+    // resets all helper tokens back to normal.
+    if (pendingJsonHelperInsert?.selectedOperands.length) {
+      const selectedReference = pendingJsonHelperInsert.selectedOperands.find((operand) => operand.kind === "reference");
+      if (!selectedReference) {
+        return null;
+      }
+      const selectedKind = referenceKindByName[selectedReference.value] || "unknown";
+      if (!helperAllowsReferenceKind(helper, selectedKind)) {
+        return t("settings.formula_fields.formula.json_builder.helper_incompatible_reason", { helper: helper.name });
+      }
+    }
+
+    return null;
+  };
+  const isReferenceCompatibleWithPendingHelper = (reference: string): boolean => {
+    if (!pendingHelperDefinition) {
+      return true;
+    }
+    const referenceKind = referenceKindByName[reference] || "unknown";
+    return helperAllowsReferenceKind(pendingHelperDefinition, referenceKind);
+  };
+  const buildHelperPlaceholderArguments = (helper: FormulaHelperDefinition): Array<{ var: string }> => {
+    const referenceCount = getHelperReferenceCount(helper);
+    if (referenceCount <= 0) {
+      return [];
+    }
+    if (referenceCount === 1) {
+      return [{ var: "value" }];
+    }
+    if (referenceCount === 2) {
+      return [{ var: "start" }, { var: "end" }];
+    }
+    return Array.from({ length: referenceCount }, (_, index) => ({ var: `arg_${index + 1}` }));
+  };
+  const helperTokenGridStyle = useMemo<CSSProperties>(
+    () => ({
+      display: "grid",
+      // Desktop uses a custom stacked layout; this fallback keeps helper groups readable on smaller screens.
+      gridTemplateColumns: screens.md || screens.sm ? "repeat(2, minmax(0, 1fr))" : "repeat(1, minmax(0, 1fr))",
+      gap: 8,
+      alignItems: "start",
+    }),
+    [screens.md, screens.sm],
+  );
+
+  // ─── Token Rendering & Insertion Logic ───
+  // This section manages the clickable token interface for building JSON expressions.
+  // Users can click operators, helpers, or field references to insert JSON snippets into the editor.
+  //
+  // Two insertion patterns:
+  // 1. Operators (logical, comparison, math): Single-stage insertion. Click operator → immediately insert
+  //    complete snippet with placeholder operands (e.g., "+ 1 1" for addition). Fast for common operations.
+  // 2. Helpers (days_between, if_then_else, etc): Two-stage insertion. Click helper → modal opens to collect
+  //    compatible references → insert complete helper with selected references. Prevents invalid combinations
+  //    and provides realtime compatibility checking (e.g., "if_then_else" requires boolean condition).
+  //
+  // Field references (custom fields, entity properties) can be inserted at any point as operand placeholders.
+  const renderTokenCategory = (
+    key: string,
+    label: string,
+    tokens: ReactNode,
+    style?: CSSProperties,
+    tokenContainerStyle?: CSSProperties,
+  ) => (
+    <div key={key} style={{ ...tokenCategoryStyle, ...style }}>
+      <Typography.Text type="secondary">
+        <strong>{label}</strong>
+      </Typography.Text>
+      <div style={tokenContainerStyle ?? tokenListStyle}>{tokens}</div>
+    </div>
+  );
+
+  // Operators: Renders logical (and/or), comparison (==/>/<), and math (+/-/*/) tokens in compact grids.
+  // Clicking an operator immediately inserts the JSON Logic snippet for that operator with placeholder
+  // operands. Disabled operators are grayed out (e.g., can't nest same operator recursively in some cases).
+  // Layout: Logical operators (2 cols), comparison (3 cols), math (3 cols) to fit JSON editor width.
+  const renderOperatorTokenGroups = (interactive: boolean) => (
+    // Compact two-column operator cells keep JSON editor width while preserving quick-click operator insertion.
+    <div style={{ display: "grid", gap: 6 }}>
+      {operatorGroups.map((group) => {
+        const compactTitle =
+          group.key === "logical"
+            ? (
+              <>
+                {t("settings.formula_fields.formula.json_builder.operator_compact.logical_top")}
+                <br />
+                {t("settings.formula_fields.formula.json_builder.operator_compact.logical_bottom")}
+              </>
+            )
+            : group.key === "comparison"
+              ? t("settings.formula_fields.formula.json_builder.operator_compact.comparison")
+              : t("settings.formula_fields.formula.json_builder.operator_compact.math");
+        const operatorGridColumns = group.key === "logical" ? "repeat(2, max-content)" : "repeat(3, max-content)";
+        const labelColumnWidth = group.key === "logical" ? 90 : 78;
+        return (
+          <div
+            key={group.key}
+            style={{
+              ...tokenCategoryStyle,
+              minHeight: 54,
+              padding: "6px 8px",
+              display: "grid",
+              gridTemplateColumns: `1fr ${labelColumnWidth}px`,
+              alignItems: "center",
+              columnGap: 6,
+            }}
+          >
+            <div
+              style={{
+                display: "grid",
+                gridTemplateColumns: operatorGridColumns,
+                gap: 3,
+                justifyItems: "center",
+                justifyContent: "start",
+              }}
+            >
+              {group.operators.map((operator) => (
+                (() => {
+                  const tokenId = `operator-${group.key}-${operator}`;
+                  const isHovered = hoveredTokenId === tokenId;
+                  const disabled = interactive ? isOperatorTokenTemporarilyDisabled(operator) : false;
+                  return (
+                    <Typography.Text
+                      key={tokenId}
+                      code
+                      style={{
+                        cursor: interactive ? (disabled ? "not-allowed" : "pointer") : "default",
+                        opacity: disabled ? 0.45 : 1,
+                        minWidth: 20,
+                        textAlign: "center",
+                        whiteSpace: "nowrap",
+                        wordBreak: "normal",
+                        overflowWrap: "normal",
+                        color: interactive && !disabled && isHovered ? token.colorWarningText : undefined,
+                        background: interactive && !disabled && isHovered ? token.colorWarningBg : undefined,
+                        borderColor: interactive && !disabled && isHovered ? token.colorWarningBorder : undefined,
+                        transition: "all 120ms ease-out",
+                      }}
+                      onMouseEnter={interactive && !disabled ? () => setHoveredTokenId(tokenId) : undefined}
+                      onMouseLeave={interactive && !disabled ? () => setHoveredTokenId((current) => (current === tokenId ? null : current)) : undefined}
+                      onClick={interactive && !disabled ? () => insertExpressionJsonOperator(operator) : undefined}
+                    >
+                      {operator}
+                    </Typography.Text>
+                  );
+                })()
+              ))}
+            </div>
+            <Typography.Text type="secondary">
+              <strong style={{ lineHeight: 1.1, fontSize: "0.92em", whiteSpace: "nowrap", textAlign: "right", display: "block" }}>
+                {compactTitle}
+              </strong>
+            </Typography.Text>
+          </div>
+        );
+      })}
+    </div>
+  );
+
+  // Helpers: Renders reusable helper functions grouped by category (date math, conditional, etc).
+  // Clicking a helper triggers the two-stage insertion flow: a modal collects which field references
+  // to include (e.g., "which spool attribute to check for days_between?"), then inserts a complete
+  // helper snippet with those references. Respects helper constraints: insert_mode (none/single/multiple),
+  // reference_count (how many fields the helper needs), value_kind (type checks for compatibility).
+  // Disabled helpers show tooltips explaining why (e.g., "no numeric fields available for math helper").
+  const renderHelperTokenCategory = (
+    groupKey: string,
+    interactive: boolean,
+    compact = false,
+  ) => {
+    const group = helperGroupByKey[groupKey];
+    if (!group || group.helpers.length === 0) {
+      return null;
+    }
+    return renderTokenCategory(
+      group.key,
+      group.label,
+      group.helpers.map((helper) => {
+        const disabledReason = interactive ? getHelperDisabledReason(helper) : null;
+        const tokenId = `helper-${helper.name}`;
+        const isHovered = hoveredTokenId === tokenId;
+        const helperToken = (
+          <Typography.Text
+            code
+            style={{
+              cursor: interactive ? (disabledReason ? "not-allowed" : "pointer") : "default",
+              opacity: disabledReason ? 0.45 : 1,
+              whiteSpace: "nowrap",
+              wordBreak: "normal",
+              overflowWrap: "normal",
+              flexShrink: 0,
+              color: interactive && !disabledReason && isHovered ? token.colorWarningText : undefined,
+              background: interactive && !disabledReason && isHovered ? token.colorWarningBg : undefined,
+              borderColor: interactive && !disabledReason && isHovered ? token.colorWarningBorder : undefined,
+              transition: "all 120ms ease-out",
+            }}
+            onMouseEnter={interactive && !disabledReason ? () => setHoveredTokenId(tokenId) : undefined}
+            onMouseLeave={interactive && !disabledReason ? () => setHoveredTokenId((current) => (current === tokenId ? null : current)) : undefined}
+            onClick={interactive && !disabledReason ? () => insertExpressionJsonHelper(helper) : undefined}
+          >
+            {helper.name}
+          </Typography.Text>
+        );
+        return (
+          <Tooltip key={`helper-${helper.name}`} title={interactive ? disabledReason || undefined : undefined}>
+            <span style={{ display: "inline-flex" }}>{helperToken}</span>
+          </Tooltip>
+        );
+      }),
+      compact ? compactHelperCategoryStyle : undefined,
+      compact ? compactHelperTokenListStyle : undefined,
+    );
+  };
+
+  // Helper layout: Desktop uses 4-column grid with preferred helper groups in top positions, others stacked below.
+  // Mobile collapses to single column. This layout accommodates ~15 helper groups across screen sizes.
+  const renderHelperTokenGroups = (interactive: boolean) => {
+    if (isDesktopLayout) {
+      return (
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: "repeat(4, minmax(0, 1fr))",
+            gap: 8,
+            alignItems: "start",
+          }}
+        >
+          {HELPER_DESKTOP_COLUMN_LAYOUT.map((column) => (
+            <div key={`helper-column-${column.top}`} style={{ display: "grid", gap: 8, alignContent: "start" }}>
+              {renderHelperTokenCategory(column.top, interactive)}
+              {column.bottom ? renderHelperTokenCategory(column.bottom, interactive, true) : null}
+            </div>
+          ))}
+        </div>
+      );
+    }
+    return (
+      <div style={helperTokenGridStyle}>
+        {helperGroups.map((group) => renderHelperTokenCategory(group.key, interactive))}
+      </div>
+    );
+  };
+
+  const missingCustomReferencesByDerivedField = useMemo(() => {
+    const availableCustomFieldKeys = new Set((configuredFields.data || []).map((field) => field.key));
+    const missingMap: Record<string, string[]> = {};
+
+    (derivedFields.data || []).forEach((derivedField) => {
+      const missingReferences = getExtraFieldReferences(derivedField.expression_json || undefined).filter(
+        (reference) => !availableCustomFieldKeys.has(reference),
+      );
+      if (missingReferences.length > 0) {
+        missingMap[derivedField.key] = missingReferences;
+      }
+    });
+
+    return missingMap;
+  }, [configuredFields.data, derivedFields.data]);
+
+  const hasBrokenFormulaDependencies = useMemo(
+    () => Object.keys(missingCustomReferencesByDerivedField).length > 0,
+    [missingCustomReferencesByDerivedField],
+  );
+
+  const openCreateDerived = () => {
+    // Reset modal UI state and pending operations when opening for new field creation.
+    // This ensures clean slate: no stale helper selections, panel states, or preview errors.
+    setEditingDerivedKey(null);
+    setPreviewText(null);
+    setPreviewErrorText(null);
+    setSampleValuesAutoUpdateEnabled(true);
+    setPendingOperatorInsert(null);
+    autoManagedSampleReferencesRef.current.clear();
+    derivedForm.resetFields();
+    derivedForm.setFieldsValue({
+      key: "",
+      name: "",
+      description: "",
+      surfaces: [FormulaFieldSurface.show],
+      include_in_api: false,
+      expression_json: "",
+      sample_values: "{}",
+    });
+    setDerivedModalOpen(true);
+  };
+
+  const openEditDerived = (record: DerivedField) => {
+    setEditingDerivedKey(record.key);
+    setPreviewText(null);
+    setPreviewErrorText(null);
+    setSampleValuesAutoUpdateEnabled(true);
+    setPendingOperatorInsert(null);
+    autoManagedSampleReferencesRef.current.clear();
+    derivedForm.setFieldsValue({
+      key: record.key,
+      name: record.name,
+      description: record.description || "",
+      surfaces: record.surfaces,
+      include_in_api: record.include_in_api ?? false,
+      expression_json: record.expression_json ? JSON.stringify(record.expression_json, null, 2) : "",
+      sample_values: "{}",
+    });
+    setDerivedModalOpen(true);
+  };
+
+  const closeDerivedModal = () => {
+    setDerivedModalOpen(false);
+    setEditingDerivedKey(null);
+    setPreviewText(null);
+    setPreviewErrorText(null);
+    setPendingJsonHelperInsert(null);
+    setPendingOperatorInsert(null);
+    autoManagedSampleReferencesRef.current.clear();
+    // Keep selection state so reopening the modal preserves cursor position
+    // expressionJsonSelectionRef is preserved intentionally
+    derivedForm.resetFields();
+  };
+
+  // Distinguish snippet/format writes from manual typing so guided IF/operator state
+  // survives programmatic editor updates instead of being cleared as "manual edits".
+  const setExpressionJsonProgrammatically = useCallback(
+    (nextValue: string) => {
+      expressionJsonProgrammaticValueRef.current = nextValue;
+      derivedForm.setFieldValue("expression_json", nextValue);
+    },
+    [derivedForm],
+  );
+
+  // Insert a JSON snippet into the expression editor while honoring any active guided
+  // operator state (including IF compare-flow) before writing final JSON text.
+  const insertExpressionJsonSnippet = (snippet: string) => {
+    let snippetToInsert = snippet;
+    let replaceEditorOnComplete = false;
+    // While an operator is pending, treat each clicked helper/reference snippet as one operand.
+    // Insert only after collecting the full required operand count for that operator.
+    if (pendingOperatorInsert) {
+      // `if` guided mode requires a comparison operator before accepting condition operands.
+      if (
+        pendingOperatorInsert.operator === "if" &&
+        pendingOperatorInsert.selectedOperands.length === 0 &&
+        !pendingOperatorInsert.pendingIfComparisonOperator
+      ) {
+        messageApi.warning("Select a comparison operator before choosing IF condition operands.");
+        return;
+      }
+      try {
+        const parsedOperand = JSON.parse(snippet) as unknown;
+        if (
+          pendingOperatorInsert.operator === "if" &&
+          pendingOperatorInsert.selectedOperands.length === 0 &&
+          pendingOperatorInsert.pendingIfComparisonOperator
+        ) {
+          const conditionOperands = [...(pendingOperatorInsert.pendingIfComparisonOperands || []), parsedOperand];
+          if (conditionOperands.length < 2) {
+            setPendingOperatorInsert({
+              ...pendingOperatorInsert,
+              pendingIfComparisonOperands: conditionOperands,
+            });
+            return;
+          }
+
+          const ifConditionNode = {
+            [pendingOperatorInsert.pendingIfComparisonOperator]: conditionOperands.slice(0, 2),
+          };
+          const selectedOperands = [ifConditionNode];
+          if (selectedOperands.length < pendingOperatorInsert.requiredOperandCount) {
+            setPendingOperatorInsert({
+              ...pendingOperatorInsert,
+              selectedOperands,
+              pendingIfComparisonOperator: null,
+              pendingIfComparisonOperands: [],
+            });
+            return;
+          }
+
+          snippetToInsert = JSON.stringify(
+            {
+              [pendingOperatorInsert.operator]: selectedOperands.slice(0, pendingOperatorInsert.requiredOperandCount),
+            },
+            null,
+            2,
+          );
+        } else {
+          const selectedOperands = [...pendingOperatorInsert.selectedOperands, parsedOperand];
+          if (selectedOperands.length < pendingOperatorInsert.requiredOperandCount) {
+            setPendingOperatorInsert({
+              ...pendingOperatorInsert,
+              selectedOperands,
+            });
+            return;
+          }
+          snippetToInsert = JSON.stringify(
+            {
+              [pendingOperatorInsert.operator]: selectedOperands.slice(0, pendingOperatorInsert.requiredOperandCount),
+            },
+            null,
+            2,
+          );
+        }
+        replaceEditorOnComplete = Boolean(pendingOperatorInsert.replaceEditorOnComplete);
+      } catch {
+        messageApi.warning(t("settings.formula_fields.formula.expression_json_invalid"));
+      }
+      setPendingOperatorInsert(null);
+    }
+
+    const currentValue = (derivedForm.getFieldValue("expression_json") as string | undefined) || "";
+    if (replaceEditorOnComplete) {
+      const nextCursor = snippetToInsert.length;
+      setExpressionJsonProgrammatically(snippetToInsert);
+      expressionJsonSelectionRef.current = { from: nextCursor, to: nextCursor };
+      requestAnimationFrame(() => {
+        const editor = expressionJsonEditorRef.current;
+        if (!editor) {
+          return;
+        }
+        editor.focus();
+        editor.dispatch({
+          selection: { anchor: nextCursor, head: nextCursor },
+          scrollIntoView: true,
+        });
+      });
+      return;
+    }
+
+    const hasEditor = expressionJsonEditorRef.current !== null;
+    if (!hasEditor) {
+      const prefix = currentValue.trim() === "" ? "" : "\n";
+      setExpressionJsonProgrammatically(`${currentValue}${prefix}${snippetToInsert}`);
+      return;
+    }
+
+    const start = expressionJsonSelectionRef.current.from;
+    const end = expressionJsonSelectionRef.current.to;
+    const nextValue = `${currentValue.slice(0, start)}${snippetToInsert}${currentValue.slice(end)}`;
+    const nextCursor = start + snippetToInsert.length;
+    setExpressionJsonProgrammatically(nextValue);
+    expressionJsonSelectionRef.current = { from: nextCursor, to: nextCursor };
+
+    requestAnimationFrame(() => {
+      const editor = expressionJsonEditorRef.current;
+      if (!editor) {
+        return;
+      }
+      editor.focus();
+      editor.dispatch({
+        selection: { anchor: nextCursor, head: nextCursor },
+        scrollIntoView: true,
+      });
+    });
+  };
+
+  const insertExpressionJsonReference = (reference: string) => {
+    if (!pendingHelperDefinition) {
+      insertExpressionJsonSnippet(JSON.stringify({ var: reference }, null, 2));
+      return;
+    }
+
+    if (!isReferenceCompatibleWithPendingHelper(reference)) {
+      messageApi.warning(
+        t("settings.formula_fields.formula.json_builder.reference_incompatible_reason", {
+          helper: pendingHelperDefinition.name,
+        }),
+      );
+      return;
+    }
+
+    const pendingState = pendingJsonHelperInsert;
+    if (!pendingState) {
+      return;
+    }
+
+    const requiredReferenceCount = getHelperReferenceCount(pendingHelperDefinition);
+    const selectedOperands = [...pendingState.selectedOperands, { kind: "reference", value: reference } as const];
+    if (selectedOperands.length < requiredReferenceCount) {
+      setPendingJsonHelperInsert({
+        helperName: pendingHelperDefinition.name,
+        selectedOperands,
+      });
+      return;
+    }
+
+    const snippet = {
+      [pendingHelperDefinition.name]: selectedOperands.slice(0, requiredReferenceCount).map((operand) => (
+        operand.kind === "reference" ? { var: operand.value } : { [operand.value]: [] }
+      )),
+    };
+    // Insert ready-to-parse JSON Logic objects so users can build expressions without memorizing
+    // raw AST syntax. Pending helper operands may be refs or helper calls like today().
+    insertExpressionJsonSnippet(JSON.stringify(snippet, null, 2));
+    setPendingJsonHelperInsert(null);
+  };
+
+  const insertExpressionJsonHelper = (helper: FormulaHelperDefinition) => {
+    // Treat today() as a valid date-diff operand while a pending helper is collecting
+    // operands, so clicks produce one combined snippet instead of standalone {"today":[]}.
+    if (pendingHelperDefinition && helper.insert_mode === "none" && helper.name === "today" && pendingHelperDefinition.category === "date_diff") {
+      const pendingState = pendingJsonHelperInsert;
+      if (!pendingState) {
+        return;
+      }
+      const requiredReferenceCount = getHelperReferenceCount(pendingHelperDefinition);
+      const selectedOperands = [...pendingState.selectedOperands, { kind: "helper", value: helper.name } as const];
+      if (selectedOperands.length < requiredReferenceCount) {
+        setPendingJsonHelperInsert({
+          helperName: pendingHelperDefinition.name,
+          selectedOperands,
+        });
+        return;
+      }
+      const snippet = {
+        [pendingHelperDefinition.name]: selectedOperands.slice(0, requiredReferenceCount).map((operand) => (
+          operand.kind === "reference" ? { var: operand.value } : { [operand.value]: [] }
+        )),
+      };
+      // Allow date-diff helpers to consume dynamic today() as an operand instead of inserting it standalone.
+      insertExpressionJsonSnippet(JSON.stringify(snippet, null, 2));
+      setPendingJsonHelperInsert(null);
+      return;
+    }
+
+    if (helper.insert_mode === "none") {
+      insertExpressionJsonSnippet(JSON.stringify({ [helper.name]: [] }, null, 2));
+      setPendingJsonHelperInsert(null);
+      return;
+    }
+    const disabledReason = getHelperDisabledReason(helper);
+    if (disabledReason) {
+      messageApi.warning(disabledReason);
+      return;
+    }
+    // Keep helper insertion staged until required reference tokens are selected, so helpers with
+    // multiple reference operands (for example days_between/hours_between) can be assembled safely.
+    setPendingJsonHelperInsert({ helperName: helper.name, selectedOperands: [] });
+    messageApi.info(
+      t("settings.formula_fields.formula.json_builder.pending_helper", {
+        helper: helper.name,
+        selected: 0,
+        total: getHelperReferenceCount(helper),
+      }),
+    );
+  };
+
+  const insertPendingHelperWithoutReferences = () => {
+    if (!pendingHelperDefinition) {
+      return;
+    }
+    const placeholderSnippet = {
+      [pendingHelperDefinition.name]: buildHelperPlaceholderArguments(pendingHelperDefinition),
+    };
+    insertExpressionJsonSnippet(JSON.stringify(placeholderSnippet, null, 2));
+    setPendingJsonHelperInsert(null);
+  };
+  const cancelPendingHelperInsert = () => {
+    setPendingJsonHelperInsert(null);
+    setPendingOperatorInsert(null);
+  };
+
+  // Handle operator-token clicks in two modes:
+  // 1) direct snippet insertion and
+  // 2) guided operand collection when starting from an empty expression.
+  const insertExpressionJsonOperator = (operator: string) => {
+    // When `if` scaffolding is active and waiting for a comparison choice, only accept
+    // comparison operators for the condition node builder.
+    if (isAwaitingIfComparisonOperator) {
+      if (!IF_CONDITION_COMPARISON_OPERATORS.has(operator)) {
+        messageApi.info(t("settings.formula_fields.formula.json_builder.if_step_condition_operator"));
+        return;
+      }
+      if (!pendingOperatorInsert) {
+        return;
+      }
+      setPendingOperatorInsert({
+        ...pendingOperatorInsert,
+        pendingIfComparisonOperator: operator,
+        pendingIfComparisonOperands: [],
+      });
+      messageApi.info(
+        t("settings.formula_fields.formula.json_builder.pending_helper", {
+          helper: "if",
+          selected: 1,
+          total: 5,
+        }),
+      );
+      return;
+    }
+
+    const currentValue = ((derivedForm.getFieldValue("expression_json") as string | undefined) || "").trim();
+    // Option 3 behavior for IF:
+    // 1) insert a readable scaffold immediately
+    // 2) keep guided click-flow active so further clicks can complete condition/then/else.
+    if (currentValue === "" && operator === "if") {
+      insertExpressionJsonSnippet(IF_SCAFFOLD_SNIPPET);
+      setPendingOperatorInsert({
+        operator,
+        selectedOperands: [],
+        requiredOperandCount: getOperatorOperandCount(operator),
+        pendingIfComparisonOperator: null,
+        pendingIfComparisonOperands: [],
+        replaceEditorOnComplete: true,
+      });
+      setPendingJsonHelperInsert(null);
+      messageApi.info(
+        t("settings.formula_fields.formula.json_builder.pending_helper", {
+          helper: operator,
+          selected: 0,
+          total: 5,
+        }),
+      );
+      return;
+    }
+
+    // Start guided operator flow on empty expressions so users can click operator -> operands
+    // and get a complete JSON snippet without placeholder vars like left/right.
+    if (currentValue === "") {
+      setPendingOperatorInsert({
+        operator,
+        selectedOperands: [],
+        requiredOperandCount: getOperatorOperandCount(operator),
+      });
+      setPendingJsonHelperInsert(null);
+      messageApi.info(
+        t("settings.formula_fields.formula.json_builder.pending_helper", {
+          helper: operator,
+          selected: 0,
+          total: getOperatorOperandCount(operator),
+        }),
+      );
+      return;
+    }
+
+    const snippet = JSON_LOGIC_OPERATOR_SNIPPETS[operator];
+    if (!snippet) {
+      return;
+    }
+    insertExpressionJsonSnippet(snippet);
+    setPendingJsonHelperInsert(null);
+  };
+
+  const formatExpressionJson = async () => {
+    try {
+      const currentValue = (derivedForm.getFieldValue("expression_json") as string | undefined) || "";
+      const parsed = parseExpressionJson(currentValue);
+      if (!parsed) {
+        return;
+      }
+      setExpressionJsonProgrammatically(JSON.stringify(parsed, null, 2));
+      messageApi.success(t("settings.formula_fields.formula.json_builder.formatted"));
+    } catch (errInfo) {
+      if (errInfo instanceof Error) {
+        messageApi.error(errInfo.message);
+      }
+    }
+  };
+
+  const saveDerived = async () => {
+    try {
+      const values = await derivedForm.validateFields();
+      const key = editingDerivedKey || values.key;
+      const expressionJson = parseExpressionJson(values.expression_json);
+      if (!expressionJson) {
+        throw new Error(t("settings.formula_fields.formula.expression_json_required"));
+      }
+      // Keep backend contract intact without exposing Result Type controls in the editor:
+      // infer from JSON when possible, otherwise preserve existing type (edit) or default new fields.
+      const inferredType = toDerivedFieldType(inferExpressionJsonType(expressionJson));
+      const existingType = editingDerivedKey
+        ? derivedFields.data?.find((field) => field.key === editingDerivedKey)?.result_type
+        : undefined;
+      const persistedResultType = inferredType ?? existingType ?? DerivedFieldType.number;
+
+      await setDerivedField.mutateAsync({
+        key,
+        params: {
+          name: values.name,
+          description: values.description || undefined,
+          result_type: persistedResultType,
+          expression_json: expressionJson,
+          surfaces: values.surfaces,
+          // List-surface formula fields are always hideable through Hide Columns. Persist this
+          // explicitly so pre-existing records with false are normalized on save.
+          allow_list_column_toggle: (values.surfaces as string[]).includes(FormulaFieldSurface.list),
+          include_in_api: values.include_in_api ?? false,
+        },
+      });
+
+      messageApi.success(
+        t(editingDerivedKey ? "settings.formula_fields.formula.messages.updated" : "settings.formula_fields.formula.messages.created", {
+          name: values.name,
+        }),
+      );
+      closeDerivedModal();
+    } catch (errInfo) {
+      if (errInfo instanceof Error) {
+        messageApi.error(errInfo.message);
+      }
+    }
+  };
+
+  // Reconcile current sample JSON against detected expression references by:
+  // 1) adding missing reference paths with type-aware defaults and
+  // 2) pruning stale keys that were auto-managed but are no longer referenced.
+  const buildSampleValuesWithMissingReferences = (currentSampleValues: Record<string, unknown>) => {
+    const mergedSampleValues = JSON.parse(JSON.stringify(currentSampleValues)) as Record<string, unknown>;
+    const insertedReferences: string[] = [];
+    const removedReferences: string[] = [];
+    const detectedReferenceSet = new Set(detectedExpressionReferences);
+
+    const trackedAutoReferences = autoManagedSampleReferencesRef.current;
+    [...trackedAutoReferences].forEach((reference) => {
+      if (detectedReferenceSet.has(reference)) {
+        return;
+      }
+      if (removeReferencePathIfPresent(mergedSampleValues, reference)) {
+        removedReferences.push(reference);
+      }
+      trackedAutoReferences.delete(reference);
+    });
+
+    detectedExpressionReferences.forEach((reference) => {
+      const referenceKind = referenceKindByName[reference] || "unknown";
+      // Seed new sample keys with type-aware defaults so previews work immediately
+      // and users can adjust values instead of building sample JSON from scratch.
+      const defaultValue = getSampleDefaultValue(
+        referenceKind,
+        reference,
+        configuredFieldByReference[reference],
+      );
+      if (insertReferencePathIfMissing(mergedSampleValues, reference, defaultValue)) {
+        insertedReferences.push(reference);
+        trackedAutoReferences.add(reference);
+      }
+    });
+
+    return {
+      mergedSampleValues,
+      insertedReferences,
+      removedReferences,
+    };
+  };
+
+  // Execute preview with request sequencing so stale async responses never overwrite
+  // newer editor state while users are typing quickly.
+  const runPreview = useCallback(async (showMessageOnError: boolean) => {
+    const requestId = previewRequestRef.current + 1;
+    previewRequestRef.current = requestId;
+    try {
+      const sampleValues = parseSampleValues((derivedForm.getFieldValue("sample_values") as string | undefined) || "{}");
+      const expressionJson = parseExpressionJson(derivedForm.getFieldValue("expression_json") as string | undefined);
+      if (!expressionJson) {
+        throw new Error(t("settings.formula_fields.formula.expression_json_required"));
+      }
+      // Preview uses sample JSON only as a sandbox for validating formulas before they are exposed
+      // on show/list/template surfaces.
+      const preview = await previewDerivedField.mutateAsync({
+        expression_json: expressionJson,
+        sample_values: sampleValues,
+      });
+
+      if (requestId !== previewRequestRef.current) {
+        return;
+      }
+      setPreviewText(formatPreviewValue(preview.result));
+      setPreviewErrorText(null);
+    } catch (errInfo) {
+      if (requestId !== previewRequestRef.current) {
+        return;
+      }
+      setPreviewText(null);
+      if (errInfo instanceof Error) {
+        setPreviewErrorText(errInfo.message);
+      } else {
+        setPreviewErrorText(t("settings.formula_fields.formula.preview.error_fallback"));
+      }
+      if (showMessageOnError && errInfo instanceof Error) {
+        messageApi.error(errInfo.message);
+      }
+    }
+  }, [derivedForm, messageApi, previewDerivedField, t]);
+
+  // Apply one synchronization pass between expression refs and sample JSON.
+  // The pass is non-destructive for user-owned keys while still cleaning stale auto-managed refs.
+  const syncMissingSampleValueKeys = (showMessageOnError: boolean) => {
+    let currentSampleValues: Record<string, unknown>;
+    try {
+      currentSampleValues = parseSampleValues((derivedForm.getFieldValue("sample_values") as string | undefined) || "{}");
+    } catch (errInfo) {
+      if (showMessageOnError && errInfo instanceof Error) {
+        messageApi.warning(errInfo.message);
+      }
+      return false;
+    }
+
+    // Apply additive scaffolding and dead-key pruning without touching user-owned sample keys.
+    const { mergedSampleValues, insertedReferences, removedReferences } = buildSampleValuesWithMissingReferences(currentSampleValues);
+
+    if (insertedReferences.length === 0 && removedReferences.length === 0) {
+      return true;
+    }
+
+    derivedForm.setFieldValue("sample_values", JSON.stringify(mergedSampleValues, null, 2));
+    return true;
+  };
+
+  useEffect(() => {
+    if (!derivedModalOpen) {
+      return;
+    }
+
+    if (!sampleValuesAutoUpdateEnabled) {
+      return;
+    }
+
+    if (((expressionJsonValue || "").trim()) === "") {
+      autoManagedSampleReferencesRef.current.clear();
+      const currentSampleValuesRaw = (derivedForm.getFieldValue("sample_values") as string | undefined) || "";
+      if (currentSampleValuesRaw.trim() !== "{}") {
+        derivedForm.setFieldValue("sample_values", "{}");
+      }
+      return;
+    }
+
+    // Ignore invalid JSON editing states so transient typing does not create stale sample keys.
+    if (parsedExpressionJson === null) {
+      return;
+    }
+
+    // Keep sample values synchronized with newly referenced variables while preserving
+    // any user-authored values that already exist in the sample JSON.
+    syncMissingSampleValueKeys(false);
+  }, [
+    derivedModalOpen,
+    expressionJsonValue,
+    detectedExpressionReferences,
+    sampleValuesValue,
+    referenceKindByName,
+    configuredFieldByReference,
+    sampleValuesAutoUpdateEnabled,
+    derivedForm,
+  ]);
+
+  useEffect(() => {
+    if (!derivedModalOpen) {
+      return;
+    }
+
+    if (((expressionJsonValue || "").trim()) === "") {
+      setPreviewText(null);
+      setPreviewErrorText(t("settings.formula_fields.formula.expression_json_required"));
+      return;
+    }
+
+    // Debounce preview with 700ms to allow formula typing without constant re-evaluation.
+    // Preview API calls can be slow, especially with complex expressions. Short debounce (350ms)
+    // would cause excessive requests during active editing. Longer debounce gives better UX.
+    const timeout = window.setTimeout(() => {
+      void runPreview(false);
+    }, 700);
+
+    return () => window.clearTimeout(timeout);
+  }, [derivedModalOpen, expressionJsonValue, sampleValuesValue, runPreview, t]);
+
+  const removeDerived = async (record: DerivedField) => {
+    try {
+      await deleteDerivedField.mutateAsync(record.key);
+      messageApi.success(t("settings.formula_fields.formula.messages.deleted", { name: record.name }));
+    } catch (errInfo) {
+      if (errInfo instanceof Error) {
+        messageApi.error(errInfo.message);
+      }
+    }
+  };
+
+  const derivedColumns: ColumnType<DerivedField>[] = [
+    {
+      title: t("settings.formula_fields.formula.columns.key"),
+      dataIndex: "key",
+      key: "key",
+      width: "10%",
+    },
+    {
+      title: t("settings.formula_fields.formula.columns.path"),
+      key: "path",
+      width: "14%",
+      render: (_: unknown, record) => <Typography.Text code>{`derived.${record.key}`}</Typography.Text>,
+    },
+    {
+      title: t("settings.formula_fields.formula.columns.name"),
+      dataIndex: "name",
+      key: "name",
+      width: "14%",
+    },
+    {
+      title: t("settings.formula_fields.formula.columns.expression"),
+      dataIndex: "expression_json",
+      key: "expression",
+      width: "34%",
+      render: (_value: Record<string, unknown> | undefined, record) => {
+        const expressionValue = record.expression_json ? JSON.stringify(record.expression_json) : "";
+        const missingReferences = missingCustomReferencesByDerivedField[record.key] || [];
+        return (
+          <Space direction="vertical" size={4}>
+            <Typography.Text code style={{ whiteSpace: "normal", wordBreak: "break-word" }}>
+              {expressionValue}
+            </Typography.Text>
+            {missingReferences.length > 0 && (
+              <Typography.Text type="danger">
+                {t("settings.formula_fields.formula.missing_references", {
+                  references: missingReferences.join(", "),
+                })}
+              </Typography.Text>
+            )}
+          </Space>
+        );
+      },
+    },
+    {
+      title: t("settings.formula_fields.formula.columns.surfaces"),
+      dataIndex: "surfaces",
+      key: "surfaces",
+      width: "20%",
+      // Keep one at-a-glance destination column by showing API as a tag alongside display surfaces.
+      render: (surfaces: string[], record) => (
+        <Space size={[4, 4]} wrap>
+          {surfaces.map((surface) => (
+            <Tag key={surface}>{t(`settings.formula_fields.surfaces.${surface}`)}</Tag>
+          ))}
+          {record.include_in_api ? <Tag color="processing">API</Tag> : null}
+        </Space>
+      ),
+    },
+    {
+      title: "",
+      key: "operation",
+      width: "12%",
+      render: (_: unknown, record) => (
+        <Space>
+          <Button onClick={() => openEditDerived(record)} size="small">
+            {t("buttons.edit")}
+          </Button>
+          <Popconfirm
+            title={t("settings.formula_fields.formula.delete_confirm", { name: record.name })}
+            onConfirm={() => removeDerived(record)}
+            okText={t("buttons.delete")}
+            cancelText={t("buttons.cancel")}
+          >
+            <Button danger size="small">
+              {t("buttons.delete")}
+            </Button>
+          </Popconfirm>
+        </Space>
+      ),
+    },
+  ];
+
+  // Render a compact side preview card beside Sample Values so result/error state stays visible
+  // without consuming extra vertical space under the editor.
+  const previewPanelContent = useMemo(() => {
+    if (previewErrorText) {
+      return (
+        <Typography.Text type="danger" style={{ textAlign: "center" }}>
+          {previewErrorText}
+        </Typography.Text>
+      );
+    }
+
+    if (previewText == null) {
+      return (
+        <Typography.Text type="secondary" style={{ textAlign: "center" }}>
+          {t("settings.formula_fields.formula.preview.empty")}
+        </Typography.Text>
+      );
+    }
+
+    return (
+      <Space direction="vertical" size={6} align="center">
+        <Typography.Text style={{ fontWeight: 600 }}>
+          <Typography.Text code>{`${derivedKeyPath} =`}</Typography.Text>
+        </Typography.Text>
+        <Typography.Text code style={{ fontSize: token.fontSizeLG + 2, lineHeight: 1.35 }}>
+          {previewText}
+        </Typography.Text>
+      </Space>
+    );
+  }, [derivedKeyPath, previewErrorText, previewText, t, token.fontSizeLG]);
+  const pendingHelperHint = useMemo<PendingHelperHintState | null>(() => {
+    if (pendingHelperDefinition && pendingJsonHelperInsert) {
+      const selected = pendingJsonHelperInsert.selectedOperands.length;
+      const total = getHelperReferenceCount(pendingHelperDefinition);
+      return {
+        helper: pendingHelperDefinition.name,
+        selected,
+        total,
+        allowHelperOnly: true,
+      };
+    }
+    if (pendingOperatorInsert) {
+      if (pendingOperatorInsert.operator === "if") {
+        const completedIfSteps = (() => {
+          if (pendingOperatorInsert.selectedOperands.length === 0) {
+            if (!pendingOperatorInsert.pendingIfComparisonOperator) {
+              return 0;
+            }
+            return 1 + (pendingOperatorInsert.pendingIfComparisonOperands?.length || 0);
+          }
+          // After condition is built, steps are:
+          // 3) compare-left-right complete + 4) then + 5) else
+          return 3 + (pendingOperatorInsert.selectedOperands.length - 1);
+        })();
+        return {
+          helper: pendingOperatorInsert.operator,
+          selected: Math.min(5, completedIfSteps),
+          total: 5,
+          allowHelperOnly: false,
+          stepLabelKey: getIfPendingStepLabelKey(pendingOperatorInsert),
+        };
+      }
+      return {
+        helper: pendingOperatorInsert.operator,
+        selected: pendingOperatorInsert.selectedOperands.length,
+        total: pendingOperatorInsert.requiredOperandCount,
+        allowHelperOnly: false,
+      };
+    }
+    return null;
+  }, [getHelperReferenceCount, pendingHelperDefinition, pendingJsonHelperInsert, pendingOperatorInsert]);
+  return (
+    <>
+      <Divider orientation="left" plain>
+        <Space size={8}>
+          <span>
+            {t("settings.formula_fields.formula.header")}: {niceName}
+          </span>
+          <Tooltip title={t("settings.formula_fields.formula.tooltip")}>
+            <QuestionCircleOutlined />
+          </Tooltip>
+          <Link
+            style={{
+              fontSize: "0.85em",
+            }}
+            to="/help#formula-fields"
+          >
+            {t("settings.formula_fields.help_links.formula")}
+          </Link>
+        </Space>
+      </Divider>
+      <Typography.Paragraph type="secondary" style={sectionBodyStyle}>
+        {t("settings.formula_fields.formula.intro")}
+      </Typography.Paragraph>
+      <Typography.Paragraph type="secondary" style={{ ...sectionBodyStyle, marginTop: -8 }}>
+        {t("settings.formula_fields.formula.evaluation_model_help")}
+      </Typography.Paragraph>
+      {hasBrokenFormulaDependencies && (
+        <Typography.Paragraph type="danger" style={{ marginTop: 0 }}>
+          {t("settings.formula_fields.formula.missing_references_intro")}
+        </Typography.Paragraph>
+      )}
+      <Typography.Paragraph type="secondary" style={{ ...sectionBodyStyle, marginBottom: 12 }}>
+        {t("settings.formula_fields.available_functions.value")}
+      </Typography.Paragraph>
+      <Table
+        columns={derivedColumns}
+        dataSource={derivedFields.data || []}
+        loading={derivedFields.isLoading}
+        pagination={false}
+        locale={{
+          emptyText: (
+            <Empty
+              description={t("settings.formula_fields.formula.empty")}
+              image={Empty.PRESENTED_IMAGE_SIMPLE}
+            />
+          ),
+        }}
+        onRow={(record) => {
+          const hasMissingReferences = (missingCustomReferencesByDerivedField[record.key] || []).length > 0;
+          if (!hasMissingReferences) {
+            return {};
+          }
+          return {
+            style: {
+              backgroundColor: token.colorErrorBg,
+            },
+          };
+        }}
+        rowKey="key"
+      />
+      <Flex justify="center">
+        <Button
+          type="primary"
+          shape="circle"
+          icon={<PlusOutlined />}
+          size="large"
+          style={{
+            margin: "1em",
+          }}
+          onClick={() => openCreateDerived()}
+        />
+      </Flex>
+
+      <Modal
+        destroyOnHidden
+        onCancel={() => closeDerivedModal()}
+        onOk={() => saveDerived()}
+        open={derivedModalOpen}
+        okText={t("buttons.save")}
+        cancelText={t("buttons.cancel")}
+        title={`${t(
+          editingDerivedKey
+            ? "settings.formula_fields.formula.modal.edit_title"
+            : "settings.formula_fields.formula.modal.create_title",
+        )}: ${niceName}`}
+        width={820}
+      >
+        <Form
+          form={derivedForm}
+          layout="vertical"
+          initialValues={{
+            surfaces: [FormulaFieldSurface.show],
+            include_in_api: false,
+            expression_json: "",
+            sample_values: "{}",
+          }}
+        >
+          {/* Responsive split: two columns on medium+ screens, stacked flow on narrow/mobile widths. */}
+          <Row gutter={12}>
+            <Col xs={24} md={12}>
+              <Form.Item
+                label={labeledField(
+                  "settings.formula_fields.formula.columns.key",
+                  "settings.formula_fields.formula.tooltips.key",
+                )}
+                name="key"
+                extra={(
+                  <Space direction="vertical" size={2} style={{ width: "100%" }}>
+                    <Typography.Text type="secondary">
+                      {t("settings.formula_fields.formula.key_usage_help")}:{" "}
+                      <Typography.Text code>{derivedKeyPath}</Typography.Text>
+                    </Typography.Text>
+                    {keyLooksLikeReservedToken && (
+                      <Typography.Text type="warning">
+                        <WarningOutlined style={{ marginRight: 6 }} />
+                        {t("settings.formula_fields.formula.key_reserved_hint", { key: derivedKeyValue })}
+                      </Typography.Text>
+                    )}
+                  </Space>
+                )}
+                rules={[
+                  { required: true, min: 1, max: 64, pattern: /^[a-z0-9_]+$/ },
+                  {
+                    validator: async (_, value) => {
+                      if (RESERVED_DERIVED_KEY_NAMES.has(value)) {
+                        throw new Error(t("settings.formula_fields.formula.key_reserved_hint", { key: value }));
+                      }
+                    },
+                  },
+                  {
+                    validator: async (_, value) => {
+                      if (!editingDerivedKey && derivedFields.data?.some((field) => field.key === value)) {
+                        throw new Error(t("settings.extra_fields.non_unique_key_error"));
+                      }
+                    },
+                  },
+                ]}
+              >
+                <Input disabled={editingDerivedKey != null} />
+              </Form.Item>
+            </Col>
+            <Col xs={24} md={12}>
+              <Form.Item
+                label={labeledField(
+                  "settings.formula_fields.formula.columns.name",
+                  "settings.formula_fields.formula.tooltips.name",
+                )}
+                name="name"
+                rules={[{ required: true, min: 1, max: 128 }]}
+              >
+                <Input />
+              </Form.Item>
+            </Col>
+          </Row>
+          <Form.Item label={t("settings.formula_fields.formula.columns.description")} name="description" rules={[{ max: 512 }]}>
+            <Input.TextArea autoSize={{ minRows: 2, maxRows: 4 }} />
+          </Form.Item>
+          <Form.Item
+            label={labeledField(
+              "settings.formula_fields.formula.columns.surfaces",
+              "settings.formula_fields.formula.tooltips.display_in",
+            )}
+            required
+          >
+            {/* Keep all visibility controls visible in one row so users can decide targets without opening menus. */}
+            <Flex align="center" gap={16} wrap>
+              <Form.Item name="surfaces" rules={[{ required: true, type: "array", min: 1 }]} noStyle>
+                <Checkbox.Group options={displaySurfaceOptions} />
+              </Form.Item>
+              <Space size={4} align="center">
+                <Form.Item name="include_in_api" valuePropName="checked" noStyle>
+                  <Checkbox>{t("settings.formula_fields.formula.display_targets.api")}</Checkbox>
+                </Form.Item>
+                <Tooltip title={t("settings.formula_fields.formula.tooltips.include_in_api")}>
+                  <QuestionCircleOutlined />
+                </Tooltip>
+              </Space>
+            </Flex>
+          </Form.Item>
+          <Form.Item
+            style={{ marginBottom: 4 }}
+            label={
+              <Flex justify="space-between" align="center" gap={8} wrap={false}>
+                <Space size={8} align="center" wrap>
+                  {labeledField(
+                    "settings.formula_fields.formula.columns.expression_json",
+                    "settings.formula_fields.formula.expression_json_help",
+                  )}
+                  <Link style={{ fontSize: "0.85em" }} to="/help#formula-json-logic">
+                    {t("settings.formula_fields.help_links.formula_json")}
+                  </Link>
+                </Space>
+              </Flex>
+            }
+            name="expression_json"
+            trigger="onChange"
+            getValueFromEvent={(value: string) => value}
+            rules={[
+              {
+                validator: async (_, value) => {
+                  const parsed = parseExpressionJson(
+                    value,
+                    t("settings.formula_fields.formula.expression_json_invalid"),
+                  );
+                  if (!parsed) {
+                    throw new Error(t("settings.formula_fields.formula.expression_json_required"));
+                  }
+                  // Validate that all referenced custom fields still exist (prevent silent formula failures after field deletion)
+                  const referencedCustomFields = getExtraFieldReferences(parsed);
+                  const availableCustomFields = new Set((configuredFields.data || []).map((field) => field.key));
+                  const missingFields = referencedCustomFields.filter((fieldKey) => !availableCustomFields.has(fieldKey));
+                  if (missingFields.length > 0) {
+                    throw new Error(
+                      t("settings.formula_fields.formula.missing_references", { references: missingFields.join(", ") }),
+                    );
+                  }
+                },
+              },
+            ]}
+          >
+            <div style={{ position: "relative" }}>
+              {/* Keep expression editor and operator rail in one row so hiding operators can
+                  immediately reclaim horizontal space without changing editor height. */}
+              <Flex align="stretch" gap={8} wrap={false}>
+                <div style={{ flex: 1, minWidth: 0 }}>
+                  <div
+                    style={{
+                      // Keep editor + operators visually balanced by default, while still allowing
+                      // manual vertical resize for longer JSON authoring sessions.
+                      height: expressionEditorHeight,
+                      minHeight: expressionEditorHeight,
+                      resize: "vertical",
+                      overflow: "auto",
+                    }}
+                  >
+                    <CodeMirror
+                      value={expressionJsonValue || ""}
+                      // Keep CodeMirror bound to the container height so dragging the resize handle
+                      // expands the visible editor instead of adding blank space below it.
+                      height="100%"
+                      style={{
+                        height: "100%",
+                        backgroundColor: token.colorBgContainer,
+                        color: token.colorText,
+                      }}
+                      extensions={[json(), drawSelection(), codeMirrorSyntaxHighlight, codeMirrorTheme]}
+                      basicSetup={{
+                        lineNumbers: true,
+                        drawSelection: false,
+                        // Keep standard editor affordances on and theme them via codeMirrorTheme.
+                        bracketMatching: true,
+                        highlightSelectionMatches: true,
+                        highlightActiveLine: false,
+                        foldGutter: true,
+                      }}
+                      onCreateEditor={(editor) => {
+                        expressionJsonEditorRef.current = editor;
+                        const mainSelection = editor.state.selection.main;
+                        expressionJsonSelectionRef.current = { from: mainSelection.from, to: mainSelection.to };
+                      }}
+                      onUpdate={(viewUpdate) => {
+                        const mainSelection = viewUpdate.state.selection.main;
+                        expressionJsonSelectionRef.current = { from: mainSelection.from, to: mainSelection.to };
+                      }}
+                      onChange={(value) => {
+                        // Ignore one editor change event when it mirrors a programmatic setFieldValue
+                        // so guided helper/operator state is only reset on actual user typing.
+                        if (expressionJsonProgrammaticValueRef.current !== null) {
+                          if (value === expressionJsonProgrammaticValueRef.current) {
+                            expressionJsonProgrammaticValueRef.current = null;
+                            return;
+                          }
+                          expressionJsonProgrammaticValueRef.current = null;
+                        }
+                        // Ignore no-op sync events where CodeMirror re-emits the same text that is
+                        // already in the form model. This prevents guided IF/operator state from
+                        // being canceled before the user clicks the next required token.
+                        const currentExpressionValue = (derivedForm.getFieldValue("expression_json") as string | undefined) || "";
+                        if (value === currentExpressionValue) {
+                          return;
+                        }
+                        // Manual edits should immediately exit guided pending insert modes.
+                        if (pendingJsonHelperInsert) {
+                          setPendingJsonHelperInsert(null);
+                        }
+                        if (pendingOperatorInsert) {
+                          setPendingOperatorInsert(null);
+                        }
+                        derivedForm.setFieldValue("expression_json", value);
+                      }}
+                    />
+                  </div>
+                  {/* Keep editor action controls anchored under the expression editor. */}
+                  <Flex
+                    justify="flex-end"
+                    align="center"
+                    gap={8}
+                    style={{ marginTop: 4 }}
+                  >
+                    <Tooltip title={t("settings.formula_fields.formula.json_builder.format_tooltip")}>
+                      <Button size="small" onClick={() => formatExpressionJson()}>
+                        {t("settings.formula_fields.formula.json_builder.format")}
+                      </Button>
+                    </Tooltip>
+                    {isDesktopOperatorPanel ? (
+                      <Tooltip
+                        title={
+                          showInlineOperatorPanel
+                            ? t("settings.formula_fields.formula.json_builder.hide_operators")
+                            : t("settings.formula_fields.formula.json_builder.show_operators")
+                        }
+                      >
+                        <Button
+                          type="default"
+                          size="small"
+                          icon={showInlineOperatorPanel ? <MenuFoldOutlined /> : <MenuUnfoldOutlined />}
+                          onClick={() => setOperatorPanelCollapsed((current) => !current)}
+                          aria-label={
+                            showInlineOperatorPanel
+                              ? t("settings.formula_fields.formula.json_builder.hide_operators")
+                              : t("settings.formula_fields.formula.json_builder.show_operators")
+                          }
+                        />
+                      </Tooltip>
+                    ) : null}
+                  </Flex>
+                </div>
+                {/* Render operator rail only when enabled so expression editor can expand right when hidden. */}
+                {showInlineOperatorPanel && (
+                  <div
+                    style={{
+                      width: OPERATOR_PANEL_WIDTH,
+                      flex: `0 0 ${OPERATOR_PANEL_WIDTH}px`,
+                      display: "flex",
+                      flexDirection: "column",
+                    }}
+                  >
+                    {/* Operator panel stays beside the editor so token insertion does not push helper/reference sections down. */}
+                    <div
+                      style={{
+                        ...tokenPanelStyle,
+                        padding: 8,
+                        height: INLINE_OPERATOR_PANEL_HEIGHT,
+                        minHeight: INLINE_OPERATOR_PANEL_HEIGHT,
+                        overflowY: "auto",
+                      }}
+                    >
+                      <Typography.Text type="secondary" style={{ display: "block", textAlign: "right" }}>
+                        <strong>{t("settings.formula_fields.formula.token_sections.operators")}</strong>
+                      </Typography.Text>
+                      <div style={{ marginTop: 8 }}>{renderOperatorTokenGroups(true)}</div>
+                    </div>
+                  </div>
+                )}
+              </Flex>
+            </div>
+          </Form.Item>
+          {/* Show helper/operators before references so helper-first insertion flow is visually guided. */}
+          <Space
+            direction="vertical"
+            size={2}
+            style={{
+              width: "100%",
+              marginBottom: 8,
+            }}
+          >
+            <Flex justify="space-between" align="center">
+              <Space size={8} align="center">
+                <Typography.Text type="secondary">
+                  <strong>{t("settings.formula_fields.formula.json_builder.operators_title")}</strong>
+                </Typography.Text>
+                <Tooltip title={t("settings.formula_fields.formula.json_builder.click_to_insert_help")}>
+                  <QuestionCircleOutlined style={{ fontSize: "0.9em" }} />
+                </Tooltip>
+                <Link
+                  style={{ fontSize: "0.85em" }}
+                  to="/help#formula-token-groups"
+                >
+                  {t("settings.formula_fields.help_links.formula_tokens")}
+                </Link>
+                <Tooltip
+                  title={
+                    tokensPanelCollapsed
+                      ? t("settings.formula_fields.formula.json_builder.show_tokens")
+                      : t("settings.formula_fields.formula.json_builder.hide_tokens")
+                  }
+                >
+                  <Button
+                    size="small"
+                    type="default"
+                    icon={tokensPanelCollapsed ? <MenuUnfoldOutlined /> : <MenuFoldOutlined />}
+                    onClick={() => setTokensPanelCollapsed((current) => !current)}
+                    aria-label={
+                      tokensPanelCollapsed
+                        ? t("settings.formula_fields.formula.json_builder.show_tokens")
+                        : t("settings.formula_fields.formula.json_builder.hide_tokens")
+                    }
+                  />
+                </Tooltip>
+              </Space>
+            </Flex>
+            {!tokensPanelCollapsed ? (
+              <>
+                <div style={tokenPanelStyle}>
+                  <Space direction="vertical" size={8} style={{ width: "100%" }}>
+                    <div>
+                      <Flex justify="space-between" align="center" gap={8} wrap={false} style={{ height: 34 }}>
+                        <Typography.Text type="secondary">
+                          <strong>{t("settings.formula_fields.formula.token_sections.helper_functions")}</strong>
+                        </Typography.Text>
+                        {/* Pending helper status + actions are placed in the header to keep insertion flow visible. */}
+                        {pendingHelperHint ? (
+                          <Space size={6} style={{ minWidth: 0, flexShrink: 0 }}>
+                            <Typography.Text type="warning" style={{ whiteSpace: "nowrap" }}>
+                              {t("settings.formula_fields.formula.json_builder.pending_helper_prefix")}
+                            </Typography.Text>
+                            <Typography.Text code style={{ color: token.colorWarningText }}>
+                              {pendingHelperHint.helper}
+                            </Typography.Text>
+                            <Typography.Text type="warning" style={{ whiteSpace: "nowrap" }}>
+                              {t("settings.formula_fields.formula.json_builder.pending_helper_count", {
+                                selected: pendingHelperHint.selected,
+                                total: pendingHelperHint.total,
+                              })}
+                            </Typography.Text>
+                            {pendingHelperHint.stepLabelKey ? (
+                              <Typography.Text type="warning" style={{ whiteSpace: "nowrap" }}>
+                                {t(pendingHelperHint.stepLabelKey)}
+                              </Typography.Text>
+                            ) : null}
+                            <Tooltip title={t("settings.formula_fields.formula.json_builder.cancel_pending_tooltip")}>
+                              <Button
+                                danger
+                                size="small"
+                                type="text"
+                                icon={<CloseCircleOutlined />}
+                                onClick={() => cancelPendingHelperInsert()}
+                                aria-label={t("settings.formula_fields.formula.json_builder.cancel_pending_tooltip")}
+                              />
+                            </Tooltip>
+                            {pendingHelperHint.allowHelperOnly ? (
+                              <Tooltip title={t("settings.formula_fields.formula.json_builder.insert_without_reference_tooltip")}>
+                                <Button
+                                  size="small"
+                                  type="primary"
+                                  onClick={() => insertPendingHelperWithoutReferences()}
+                                  aria-label={t("settings.formula_fields.formula.json_builder.insert_without_reference_tooltip")}
+                                >
+                                  {t("settings.formula_fields.formula.json_builder.helper_only")}
+                                </Button>
+                              </Tooltip>
+                            ) : null}
+                          </Space>
+                        ) : null}
+                      </Flex>
+                      <div style={{ marginTop: 6 }}>{renderHelperTokenGroups(true)}</div>
+                    </div>
+                    <div style={{ paddingTop: 4 }}>
+                      <Flex align="center" gap={8}>
+                        <Typography.Text type="secondary">
+                          <strong>{t("settings.formula_fields.formula.reference_picker.label")}</strong>
+                        </Typography.Text>
+                        <Tooltip title={t("settings.formula_fields.formula.json_builder.click_to_insert_help")}>
+                          <QuestionCircleOutlined style={{ fontSize: "0.9em" }} />
+                        </Tooltip>
+                      </Flex>
+                      <div style={{ ...tokenCategoryStyle, marginTop: 6 }}>
+                        <div style={referenceGridStyle}>
+                          {compactReferenceOptions.map((reference) => {
+                            const referenceCompatible = isReferenceCompatibleWithPendingHelper(reference.value);
+                            const isSelectedForPendingHelper = Boolean(
+                              pendingJsonHelperInsert?.selectedOperands.some(
+                                (operand) => operand.kind === "reference" && operand.value === reference.value,
+                              ),
+                            );
+                            const disabledReason =
+                              !referenceCompatible && pendingHelperDefinition
+                                ? t("settings.formula_fields.formula.json_builder.reference_incompatible_reason", {
+                                    helper: pendingHelperDefinition.name,
+                                  })
+                                : null;
+                            const referenceToken = (
+                              <Typography.Text
+                                code
+                                style={{
+                                  cursor: disabledReason ? "not-allowed" : "pointer",
+                                  opacity: disabledReason ? 0.45 : 1,
+                                  whiteSpace: "nowrap",
+                                  overflow: "hidden",
+                                  textOverflow: "ellipsis",
+                                  textAlign: "center",
+                                  fontWeight: 500,
+                                  color: isSelectedForPendingHelper
+                                    ? token.colorPrimaryText
+                                    : (!disabledReason && hoveredTokenId === `reference-${reference.value}` ? token.colorWarningText : undefined),
+                                  background:
+                                    !disabledReason && hoveredTokenId === `reference-${reference.value}` ? token.colorWarningBg : undefined,
+                                  borderColor:
+                                    !disabledReason && hoveredTokenId === `reference-${reference.value}`
+                                      ? token.colorWarningBorder
+                                      : undefined,
+                                  transition: "all 120ms ease-out",
+                                }}
+                                onMouseEnter={!disabledReason ? () => setHoveredTokenId(`reference-${reference.value}`) : undefined}
+                                onMouseLeave={!disabledReason ? () => setHoveredTokenId((current) => (current === `reference-${reference.value}` ? null : current)) : undefined}
+                                onClick={!disabledReason ? () => insertExpressionJsonReference(reference.value) : undefined}
+                              >
+                                {reference.label}
+                              </Typography.Text>
+                            );
+                            // Keep a stable wrapper shape for all reference tokens so disabled/tooltip states
+                            // do not cause reflow when helper compatibility changes.
+                            const content = (
+                              <Tooltip title={disabledReason || undefined}>
+                                <span style={{ display: "inline-flex", justifyContent: "center" }}>{referenceToken}</span>
+                              </Tooltip>
+                            );
+                            return (
+                              <div
+                                key={`reference-cell-${reference.value}`}
+                                style={{ display: "flex", justifyContent: "center", alignItems: "center", minHeight: 24 }}
+                              >
+                                {content}
+                              </div>
+                            );
+                          })}
+                        </div>
+                      </div>
+                    </div>
+                  </Space>
+                </div>
+              </>
+            ) : null}
+          </Space>
+          <Form.Item
+            name="sample_values"
+            rules={[
+              {
+                validator: async (_, value) => {
+                  parseSampleValues(
+                    value,
+                    t("settings.formula_fields.formula.sample_values_invalid"),
+                  );
+                },
+              },
+            ]}
+          >
+            <Space direction="vertical" size={8} style={{ width: "100%" }}>
+              {/* Keep labels in one row and content in the next so Preview is clearly outside the card. */}
+              <Row gutter={8} align="middle" wrap={!isDesktopLayout}>
+                <Col flex="auto" style={{ minWidth: 0 }}>
+                  <Space size={10} wrap>
+                    {labeledField("settings.formula_fields.formula.sample_values", "settings.formula_fields.formula.tooltips.sample_values")}
+                    <Space size={6}>
+                      <Typography.Text type="secondary">Auto-update</Typography.Text>
+                      <Switch
+                        size="small"
+                        checked={sampleValuesAutoUpdateEnabled}
+                        onChange={(checked) => setSampleValuesAutoUpdateEnabled(checked)}
+                      />
+                    </Space>
+                  </Space>
+                </Col>
+                <Col flex={isDesktopLayout ? `${OPERATOR_PANEL_WIDTH}px` : "100%"}>
+                  <Space size={4}>
+                    <span>{t("settings.formula_fields.formula.preview.panel_title")}</span>
+                  </Space>
+                </Col>
+              </Row>
+              <Row gutter={[8, 8]} align="top" wrap={!isDesktopLayout}>
+                <Col flex={isDesktopLayout ? "auto" : "100%"} style={{ minWidth: 0 }}>
+                  <div
+                    style={{
+                      height: 78,
+                      minHeight: 78,
+                      resize: "vertical",
+                      overflow: "auto",
+                    }}
+                  >
+                    <CodeMirror
+                      value={sampleValuesValue || ""}
+                      height="100%"
+                      style={{
+                        height: "100%",
+                        backgroundColor: token.colorBgContainer,
+                        color: token.colorText,
+                      }}
+                      extensions={[json(), drawSelection(), codeMirrorSyntaxHighlight, codeMirrorTheme]}
+                      basicSetup={{
+                        lineNumbers: false,
+                        drawSelection: false,
+                        bracketMatching: true,
+                        highlightSelectionMatches: true,
+                        highlightActiveLine: false,
+                        foldGutter: false,
+                      }}
+                      placeholder={sampleValuesPlaceholder}
+                      onChange={(value) => {
+                        derivedForm.setFieldValue("sample_values", value);
+                      }}
+                    />
+                  </div>
+                </Col>
+                <Col flex={isDesktopLayout ? `${OPERATOR_PANEL_WIDTH}px` : "100%"}>
+                  <div
+                    style={{
+                      ...tokenPanelStyle,
+                      minHeight: 78,
+                      display: "flex",
+                      alignItems: "center",
+                      justifyContent: "center",
+                      textAlign: "center",
+                      padding: 8,
+                    }}
+                  >
+                    <div style={{ minHeight: 52, display: "flex", alignItems: "center", justifyContent: "center" }}>
+                      {previewPanelContent}
+                    </div>
+                  </div>
+                </Col>
+              </Row>
+              {/* Surface detected references and clearly mark only invalid/undefined entries.
+                  Missing paths are auto-scaffolded while typing and preview updates automatically. */}
+              <Flex align="center" gap={8} wrap="wrap">
+                <Space size={[6, 6]} wrap>
+                  <Typography.Text type="secondary">
+                    <strong>{t("settings.formula_fields.formula.sample_values_detected_references")}</strong>
+                  </Typography.Text>
+                  {detectedExpressionReferences.length > 0 ? (
+                    detectedExpressionReferences.map((reference) => {
+                      const isDefined = hasValidSampleValues && !missingSampleValueReferences.includes(reference);
+                      const statusTooltip = isDefined
+                        ? undefined
+                        : t("settings.formula_fields.formula.sample_values_reference_invalid");
+                      const referenceText = (
+                        <Typography.Text
+                          key={`sample-ref-${reference}`}
+                          code
+                          style={isDefined ? undefined : { color: token.colorErrorText, borderColor: token.colorErrorBorder }}
+                        >
+                          {reference}
+                        </Typography.Text>
+                      );
+                      return (
+                        <Tooltip key={`sample-ref-tooltip-${reference}`} title={statusTooltip}>
+                          <span>{referenceText}</span>
+                        </Tooltip>
+                      );
+                    })
+                  ) : (
+                    <Typography.Text type="secondary">
+                      {t("settings.formula_fields.formula.sample_values_detected_references_empty")}
+                    </Typography.Text>
+                  )}
+                </Space>
+              </Flex>
+            </Space>
+          </Form.Item>
+        </Form>
+      </Modal>
+      {contextHolder}
+    </>
+  );
+}
diff --git a/client/src/pages/spools/list.tsx b/client/src/pages/spools/list.tsx
index e710f1368..92165a1a0 100644
--- a/client/src/pages/spools/list.tsx
+++ b/client/src/pages/spools/list.tsx
@@ -36,7 +36,7 @@ import {
   useSpoolmanMaterials,
 } from "../../components/otherModels";
 import { removeUndefined } from "../../utils/filtering";
-import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
+import { FormulaFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { TableState, useInitialTableState, useSavedState, useStoreInitialState } from "../../utils/saveload";
 import { useCurrencyFormatter } from "../../utils/settings";
 import { setSpoolArchived, useSpoolAdjustModal } from "./functions";
@@ -181,16 +181,14 @@ export const SpoolList = () => {
   );
   const liveDataSource = useLiveify("spool", queryDataSource, collapseSpool);
   const listFormulaFields = useMemo(
-    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.list),
+    () => getFormulaFieldsForSurface(formulaFields.data, FormulaFieldSurface.list),
     [formulaFields.data],
   );
-  const toggleableListFormulaFields = useMemo(
-    () => listFormulaFields.filter((field) => field.allow_list_column_toggle),
-    [listFormulaFields],
-  );
+  // All list-surface formula fields are eligible for hide/show in the column picker,
+  // so we map every list formula to its derived column key here.
   const toggleableDerivedColumnKeys = useMemo(
-    () => toggleableListFormulaFields.map((field) => `derived.${field.key}`),
-    [toggleableListFormulaFields],
+    () => listFormulaFields.map((field) => `derived.${field.key}`),
+    [listFormulaFields],
   );
   const allColumnsWithExtraFields = useMemo(
     () => [
@@ -295,6 +293,8 @@ export const SpoolList = () => {
   };
 
   const updateColumnSelections = (selectedKeys: string[]) => {
+    // Persist core column visibility separately from derived-column visibility so
+    // derived keys can be toggled without rewriting the base showColumns state.
     setShowColumns(selectedKeys.filter((key) => !toggleableDerivedColumnKeys.includes(key)));
     setHiddenDerivedColumns(toggleableDerivedColumnKeys.filter((key) => !selectedKeys.includes(key)));
   };
@@ -344,7 +344,7 @@ export const SpoolList = () => {
                   };
                 }
                 if (column_id.indexOf("derived.") === 0) {
-                  const formulaField = toggleableListFormulaFields.find((field) => `derived.${field.key}` === column_id);
+                  const formulaField = listFormulaFields.find((field) => `derived.${field.key}` === column_id);
                   return {
                     key: column_id,
                     label: formulaField?.name ?? column_id,
@@ -510,7 +510,7 @@ export const SpoolList = () => {
           ...listFormulaFields.map(
             (field) => {
               const derivedColumnKey = `derived.${field.key}`;
-              if (field.allow_list_column_toggle && hiddenDerivedColumns.includes(derivedColumnKey)) {
+              if (hiddenDerivedColumns.includes(derivedColumnKey)) {
                 return undefined;
               }
 
diff --git a/client/src/pages/spools/show.tsx b/client/src/pages/spools/show.tsx
index e86a70c93..c0cead4f3 100644
--- a/client/src/pages/spools/show.tsx
+++ b/client/src/pages/spools/show.tsx
@@ -10,7 +10,7 @@ import { NumberFieldUnit } from "../../components/numberField";
 import SpoolIcon from "../../components/spoolIcon";
 import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import { enrichText } from "../../utils/parsing";
-import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
+import { FormulaFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { useCurrencyFormatter } from "../../utils/settings";
 import { getBasePath } from "../../utils/url";
 import { IFilament } from "../filaments/model";
@@ -36,7 +36,7 @@ export const SpoolShow = () => {
 
   const record = data?.data;
   const showFormulaFields = useMemo(
-    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.show),
+    () => getFormulaFieldsForSurface(formulaFields.data, FormulaFieldSurface.show),
     [formulaFields.data],
   );
   const derivedValues = useMemo(
@@ -234,7 +234,7 @@ export const SpoolShow = () => {
       {extraFields?.data?.map((field, index) => (
         <ExtraFieldDisplay key={index} field={field} value={record?.extra[field.key]} />
       ))}
-      {showFormulaFields.length > 0 && <Title level={4}>{t("settings.complex_fields.formula.header")}</Title>}
+      {showFormulaFields.length > 0 && <Title level={4}>{t("settings.formula_fields.formula.header")}</Title>}
       {showFormulaFields.map((field) => (
         <Fragment key={field.key}>
           <Title level={5}>{field.name}</Title>
diff --git a/client/src/pages/vendors/list.tsx b/client/src/pages/vendors/list.tsx
index 7ceb000c0..0c40fe5ac 100644
--- a/client/src/pages/vendors/list.tsx
+++ b/client/src/pages/vendors/list.tsx
@@ -18,7 +18,7 @@ import {
 import { useLiveify } from "../../components/liveify";
 import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import { removeUndefined } from "../../utils/filtering";
-import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
+import { FormulaFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { TableState, useInitialTableState, useSavedState, useStoreInitialState } from "../../utils/saveload";
 import { IVendor } from "./model";
 
@@ -91,16 +91,14 @@ export const VendorList = () => {
     useCallback((record: IVendor) => record, []),
   );
   const listFormulaFields = useMemo(
-    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.list),
+    () => getFormulaFieldsForSurface(formulaFields.data, FormulaFieldSurface.list),
     [formulaFields.data],
   );
-  const toggleableListFormulaFields = useMemo(
-    () => listFormulaFields.filter((field) => field.allow_list_column_toggle),
-    [listFormulaFields],
-  );
+  // All list-surface formula fields are eligible for hide/show in the column picker,
+  // so we map every list formula to its derived column key here.
   const toggleableDerivedColumnKeys = useMemo(
-    () => toggleableListFormulaFields.map((field) => `derived.${field.key}`),
-    [toggleableListFormulaFields],
+    () => listFormulaFields.map((field) => `derived.${field.key}`),
+    [listFormulaFields],
   );
   const allColumnsWithExtraFields = useMemo(
     () => [
@@ -146,6 +144,8 @@ export const VendorList = () => {
   };
 
   const updateColumnSelections = (selectedKeys: string[]) => {
+    // Persist core column visibility separately from derived-column visibility so
+    // derived keys can be toggled without rewriting the base showColumns state.
     setShowColumns(selectedKeys.filter((key) => !toggleableDerivedColumnKeys.includes(key)));
     setHiddenDerivedColumns(toggleableDerivedColumnKeys.filter((key) => !selectedKeys.includes(key)));
   };
@@ -177,7 +177,7 @@ export const VendorList = () => {
                   };
                 }
                 if (column_id.indexOf("derived.") === 0) {
-                  const formulaField = toggleableListFormulaFields.find((field) => `derived.${field.key}` === column_id);
+                  const formulaField = listFormulaFields.find((field) => `derived.${field.key}` === column_id);
                   return {
                     key: column_id,
                     label: formulaField?.name ?? column_id,
@@ -250,7 +250,7 @@ export const VendorList = () => {
           ...listFormulaFields.map(
             (field) => {
               const derivedColumnKey = `derived.${field.key}`;
-              if (field.allow_list_column_toggle && hiddenDerivedColumns.includes(derivedColumnKey)) {
+              if (hiddenDerivedColumns.includes(derivedColumnKey)) {
                 return undefined;
               }
 
diff --git a/client/src/pages/vendors/show.tsx b/client/src/pages/vendors/show.tsx
index 9404c2c55..803ec91bc 100644
--- a/client/src/pages/vendors/show.tsx
+++ b/client/src/pages/vendors/show.tsx
@@ -7,7 +7,7 @@ import utc from "dayjs/plugin/utc";
 import { ExtraFieldDisplay } from "../../components/extraFields";
 import { buildFormulaValues, formatFormulaValue, getFormulaFieldsForSurface } from "../../utils/formulaFields";
 import { enrichText } from "../../utils/parsing";
-import { ComplexFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
+import { FormulaFieldSurface, EntityType, useGetDerivedFields, useGetFields } from "../../utils/queryFields";
 import { IVendor } from "./model";
 
 dayjs.extend(utc);
@@ -26,7 +26,7 @@ export const VendorShow = () => {
 
   const record = data?.data;
   const showFormulaFields = useMemo(
-    () => getFormulaFieldsForSurface(formulaFields.data, ComplexFieldSurface.show),
+    () => getFormulaFieldsForSurface(formulaFields.data, FormulaFieldSurface.show),
     [formulaFields.data],
   );
   const derivedValues = useMemo(
@@ -60,7 +60,7 @@ export const VendorShow = () => {
       {extraFields?.data?.map((field, index) => (
         <ExtraFieldDisplay key={index} field={field} value={record?.extra[field.key]} />
       ))}
-      {showFormulaFields.length > 0 && <Title level={4}>{t("settings.complex_fields.formula.header")}</Title>}
+      {showFormulaFields.length > 0 && <Title level={4}>{t("settings.formula_fields.formula.header")}</Title>}
       {showFormulaFields.map((field) => (
         <Fragment key={field.key}>
           <Title level={5}>{field.name}</Title>
diff --git a/client/src/utils/formulaFields.ts b/client/src/utils/formulaFields.ts
index 95c04cfb9..f94c20d26 100644
--- a/client/src/utils/formulaFields.ts
+++ b/client/src/utils/formulaFields.ts
@@ -1,4 +1,4 @@
-import { ComplexFieldSurface, DerivedField } from "./queryFields";
+import { FormulaFieldSurface, DerivedField } from "./queryFields";
 
 type FormulaScope = object;
 
@@ -174,6 +174,8 @@ function asNumber(value: unknown, operator: string): number {
 }
 
 function parseExtraValue(value: unknown): unknown {
+  // Extra fields are serialized in API payloads; parse opportunistically so formula
+  // evaluation can treat numbers/booleans/dates as values instead of raw strings.
   if (typeof value !== "string") {
     return value;
   }
@@ -184,6 +186,44 @@ function parseExtraValue(value: unknown): unknown {
   }
 }
 
+function normalizeFormulaScopeValue(value: unknown): unknown {
+  // Normalize recursively so formula evaluation sees a stable shape for nested data,
+  // including parsed `extra.*` payloads and dual datetime aliases.
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeFormulaScopeValue(item));
+  }
+
+  if (isRecord(value)) {
+    const normalized: Record<string, unknown> = {};
+    Object.entries(value).forEach(([key, nested]) => {
+      if (key === "extra" && isRecord(nested)) {
+        normalized[key] = Object.fromEntries(
+          Object.entries(nested).map(([extraKey, extraValue]) => [extraKey, parseExtraValue(extraValue)]),
+        );
+        return;
+      }
+      normalized[key] = normalizeFormulaScopeValue(nested);
+    });
+
+    // Preserve both keys for compatibility with existing formulas authored with either naming.
+    if ("registered" in normalized && !("created_at" in normalized)) {
+      normalized.created_at = normalized.registered;
+    }
+    if ("created_at" in normalized && !("registered" in normalized)) {
+      normalized.registered = normalized.created_at;
+    }
+    return normalized;
+  }
+
+  return value;
+}
+
+function normalizeFormulaScope(scope: FormulaScope): Record<string, unknown> {
+  // Ensure the evaluator always receives an object root even if caller input is malformed.
+  const normalized = normalizeFormulaScopeValue(scope);
+  return isRecord(normalized) ? normalized : {};
+}
+
 function getReferenceValue(reference: string, scope: FormulaScope): unknown {
   const parts = reference.split(".");
   let current: unknown = scope;
@@ -210,12 +250,20 @@ function getReferenceValue(reference: string, scope: FormulaScope): unknown {
   return current;
 }
 
-function collectFormulaReferencesFromJsonLogic(node: unknown, references: Set<string>): void {
+// Defensive recursion with depth limit to prevent stack overflow on malformed expressions.
+// Most real JSON Logic expressions are 3-4 levels deep; 20 provides ample margin for complex nesting.
+const MAX_JSON_LOGIC_RECURSION_DEPTH = 20;
+
+function collectFormulaReferencesFromJsonLogic(node: unknown, references: Set<string>, depth = 0): void {
+  if (depth > MAX_JSON_LOGIC_RECURSION_DEPTH) {
+    // Silently stop traversal at max depth to prevent stack overflow.
+    return;
+  }
   if (node === null || typeof node === "string" || typeof node === "number" || typeof node === "boolean") {
     return;
   }
   if (Array.isArray(node)) {
-    node.forEach((value) => collectFormulaReferencesFromJsonLogic(value, references));
+    node.forEach((value) => collectFormulaReferencesFromJsonLogic(value, references, depth + 1));
     return;
   }
   if (!isRecord(node)) {
@@ -235,12 +283,12 @@ function collectFormulaReferencesFromJsonLogic(node: unknown, references: Set<st
       references.add(reference);
     }
     if (args.length > 1) {
-      collectFormulaReferencesFromJsonLogic(args[1], references);
+      collectFormulaReferencesFromJsonLogic(args[1], references, depth + 1);
     }
     return;
   }
 
-  args.forEach((arg) => collectFormulaReferencesFromJsonLogic(arg, references));
+  args.forEach((arg) => collectFormulaReferencesFromJsonLogic(arg, references, depth + 1));
 }
 
 export function getFormulaReferencesFromJsonLogic(expressionJson: Record<string, unknown>): string[] {
@@ -500,22 +548,25 @@ export function evaluateFormulaJsonLogic(expressionJson: Record<string, unknown>
 }
 
 export function getTemplateFormulaFields(fields: DerivedField[] | undefined): DerivedField[] {
-  return (fields || []).filter((field) => field.surfaces.includes(ComplexFieldSurface.template));
+  return (fields || []).filter((field) => field.surfaces.includes(FormulaFieldSurface.template));
 }
 
 export function getFormulaFieldsForSurface(
   fields: DerivedField[] | undefined,
-  surface: ComplexFieldSurface,
+  surface: FormulaFieldSurface,
 ): DerivedField[] {
   return (fields || []).filter((field) => field.surfaces.includes(surface));
 }
 
 export function buildFormulaValues(scope: FormulaScope, fields: DerivedField[]): Record<string, unknown> {
   const values: Record<string, unknown> = {};
+  // Evaluate against the normalized scope once per row so each field sees identical
+  // compatibility aliases (registered/created_at) and parsed extra values.
+  const normalizedScope = normalizeFormulaScope(scope);
   fields.forEach((field) => {
     try {
       if (field.expression_json) {
-        values[field.key] = evaluateFormulaJsonLogic(field.expression_json, scope);
+        values[field.key] = evaluateFormulaJsonLogic(field.expression_json, normalizedScope);
       }
     } catch {
       // Failed evaluations stay hidden so one invalid formula does not break show/list/template
diff --git a/client/src/utils/queryFields.ts b/client/src/utils/queryFields.ts
index 9b3fe6f89..41069248c 100644
--- a/client/src/utils/queryFields.ts
+++ b/client/src/utils/queryFields.ts
@@ -19,7 +19,8 @@ export enum EntityType {
   spool = "spool",
 }
 
-export enum ComplexFieldSurface {
+// Shared surface identifiers for formula fields across settings, list/show pages, and templates.
+export enum FormulaFieldSurface {
   show = "show",
   edit = "edit",
   list = "list",
diff --git a/scripts/pr-preflight.sh b/scripts/pr-preflight.sh
deleted file mode 100755
index 703c7ad8d..000000000
--- a/scripts/pr-preflight.sh
+++ /dev/null
@@ -1,174 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<'EOF'
-Usage:
-  scripts/pr-preflight.sh <pr> [options]
-
-Examples:
-  scripts/pr-preflight.sh 874 --expected-worktree /private/tmp/spoolman_pr874_runtime_iQoS --expected-branch feat/complex-fields-framework --strict
-  scripts/pr-preflight.sh 874 --expected-worktree /private/tmp/spoolman_pr874_runtime_iQoS --expected-branch feat/complex-fields-framework --strict --require-container --require-url
-  scripts/pr-preflight.sh 876 --expected-branch tmp/pr876-template-filters --strict
-
-Options:
-  --expected-worktree <abs-path>   Exact worktree path required for strict checks.
-  --expected-branch <name>         Exact branch name required for strict checks.
-  --require-container              Require spoolman_pr<PR>_8<PR> to be running.
-  --require-url                    Require localhost:8<PR> to respond with HTTP status.
-  --strict                         Exit non-zero when any mismatch is found.
-EOF
-}
-
-if [[ "${1:-}" == "" || "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
-  usage
-  exit 0
-fi
-
-if ! [[ "$1" =~ ^[0-9]+$ ]]; then
-  echo "ERROR: first argument must be a numeric PR id." >&2
-  usage
-  exit 1
-fi
-
-PR="$1"
-shift
-
-EXPECTED_WORKTREE=""
-EXPECTED_BRANCH=""
-REQUIRE_CONTAINER=0
-REQUIRE_URL=0
-STRICT=0
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --expected-worktree)
-      EXPECTED_WORKTREE="${2:-}"
-      shift 2
-      ;;
-    --expected-branch)
-      EXPECTED_BRANCH="${2:-}"
-      shift 2
-      ;;
-    --require-container)
-      REQUIRE_CONTAINER=1
-      shift
-      ;;
-    --require-url)
-      REQUIRE_URL=1
-      shift
-      ;;
-    --strict)
-      STRICT=1
-      shift
-      ;;
-    *)
-      echo "ERROR: unknown option: $1" >&2
-      usage
-      exit 1
-      ;;
-  esac
-done
-
-if ! git rev-parse --show-toplevel >/dev/null 2>&1; then
-  echo "ERROR: not inside a git repository." >&2
-  exit 1
-fi
-
-CURRENT_PWD="$(pwd -P)"
-REPO_ROOT="$(git rev-parse --show-toplevel)"
-CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
-HEAD_LINE="$(git log --oneline -n 1)"
-
-PORT="8${PR}"
-CONTAINER="spoolman_pr${PR}_${PORT}"
-DB_PATH="/tmp/spoolman_pr_${PR}_data"
-URL="http://localhost:${PORT}"
-
-echo "PR            : #${PR}"
-echo "Repo Root     : ${REPO_ROOT}"
-echo "Worktree      : ${CURRENT_PWD}"
-echo "Branch        : ${CURRENT_BRANCH}"
-echo "HEAD          : ${HEAD_LINE}"
-echo "Container     : ${CONTAINER}"
-echo "Port          : ${PORT}"
-echo "DB Mount      : ${DB_PATH}"
-echo "URL           : ${URL}"
-echo "Strict Mode   : ${STRICT}"
-
-ERRORS=0
-WARNINGS=0
-
-if [[ -n "${EXPECTED_WORKTREE}" && "${CURRENT_PWD}" != "${EXPECTED_WORKTREE}" ]]; then
-  echo "MISMATCH: worktree '${CURRENT_PWD}' != expected '${EXPECTED_WORKTREE}'" >&2
-  ERRORS=1
-fi
-
-if [[ -n "${EXPECTED_BRANCH}" && "${CURRENT_BRANCH}" != "${EXPECTED_BRANCH}" ]]; then
-  echo "MISMATCH: branch '${CURRENT_BRANCH}' != expected '${EXPECTED_BRANCH}'" >&2
-  ERRORS=1
-fi
-
-if [[ "${CURRENT_BRANCH}" == "HEAD" ]]; then
-  echo "MISMATCH: detached HEAD detected. Switch to the PR branch before editing." >&2
-  ERRORS=1
-fi
-
-# If no explicit expected values are provided, still surface a context warning when
-# neither path nor branch appears to include the PR id.
-if [[ -z "${EXPECTED_WORKTREE}" && -z "${EXPECTED_BRANCH}" ]]; then
-  if ! [[ "${CURRENT_PWD}" =~ ${PR} || "${CURRENT_BRANCH}" =~ ${PR} ]]; then
-    echo "WARNING: PR id '${PR}' not found in current worktree path or branch name." >&2
-    WARNINGS=1
-  fi
-fi
-
-if command -v docker >/dev/null 2>&1; then
-  echo "Docker        :"
-  CONTAINER_LINE="$(docker ps --format '{{.Names}}\t{{.Status}}\t{{.Ports}}' | awk -v name="${CONTAINER}" '$1 == name {print $0}')"
-  if [[ -n "${CONTAINER_LINE}" ]]; then
-    echo "  ${CONTAINER_LINE}"
-  else
-    echo "  (not running)"
-    if [[ "${REQUIRE_CONTAINER}" -eq 1 ]]; then
-      echo "MISMATCH: required container '${CONTAINER}' is not running." >&2
-      ERRORS=1
-    fi
-  fi
-else
-  echo "Docker        : not found"
-  if [[ "${REQUIRE_CONTAINER}" -eq 1 ]]; then
-    echo "MISMATCH: --require-container specified but docker is not available." >&2
-    ERRORS=1
-  fi
-fi
-
-if [[ "${REQUIRE_URL}" -eq 1 ]]; then
-  if command -v curl >/dev/null 2>&1; then
-    HTTP_CODE="$(curl -sS -o /dev/null -w '%{http_code}' "${URL}" || true)"
-    echo "URL Probe     : ${HTTP_CODE}"
-    if [[ "${HTTP_CODE}" == "000" ]]; then
-      echo "MISMATCH: URL '${URL}' is not reachable." >&2
-      ERRORS=1
-    fi
-  else
-    echo "URL Probe     : curl not found"
-    echo "MISMATCH: --require-url specified but curl is not available." >&2
-    ERRORS=1
-  fi
-fi
-
-if [[ "${ERRORS}" -eq 0 ]]; then
-  if [[ "${WARNINGS}" -eq 0 ]]; then
-    echo "RESULT        : PASS"
-  else
-    echo "RESULT        : PASS (with warnings)"
-  fi
-else
-  echo "RESULT        : FAIL"
-fi
-
-if [[ "${STRICT}" -eq 1 && "${ERRORS}" -ne 0 ]]; then
-  echo "ERROR: strict preflight failed." >&2
-  exit 2
-fi
diff --git a/spoolman/derived_fields.py b/spoolman/derived_fields.py
index 419224c9e..3f623a45a 100644
--- a/spoolman/derived_fields.py
+++ b/spoolman/derived_fields.py
@@ -81,15 +81,18 @@ class DerivedFieldPreviewResponse(BaseModel):
 
 
 def _as_datetime(value: Any) -> datetime:
+    # Normalize all datetime operands to timezone-aware UTC so interval helpers
+    # (days_between/hours_between) can safely compare mixed user inputs (with/without timezone).
     if isinstance(value, datetime):
-        return value
+        return value if value.tzinfo is not None else value.replace(tzinfo=timezone.utc)
     if isinstance(value, date):
-        return datetime.combine(value, time.min)
+        return datetime.combine(value, time.min, tzinfo=timezone.utc)
     if isinstance(value, str):
         normalized = value.strip()
         if normalized.endswith("Z"):
             normalized = f"{normalized[:-1]}+00:00"
-        return datetime.fromisoformat(normalized)
+        parsed = datetime.fromisoformat(normalized)
+        return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=timezone.utc)
     raise ValueError(f"Value {value!r} is not a datetime-compatible input.")
 
 
@@ -438,6 +441,8 @@ def _validate_expression_payload(expression_json: dict[str, Any]) -> None:
 
 
 def _parse_extra_field_value(value: Any) -> Any:
+    # Extra-field values are persisted as JSON strings; parse when possible so
+    # formula operators evaluate real typed values instead of quoted text.
     if not isinstance(value, str):
         return value
     try:
@@ -447,6 +452,8 @@ def _parse_extra_field_value(value: Any) -> Any:
 
 
 def _normalize_formula_scope(value: Any) -> Any:
+    # Normalize nested payloads recursively so derived evaluation sees stable types
+    # and compatibility aliases regardless of API/UI serialization differences.
     if isinstance(value, dict):
         normalized: dict[str, Any] = {}
         for key, nested in value.items():
@@ -457,6 +464,13 @@ def _normalize_formula_scope(value: Any) -> Any:
                 }
                 continue
             normalized[key] = _normalize_formula_scope(nested)
+
+        # Preserve both naming conventions so existing formulas written against either
+        # "registered" or "created_at" keep evaluating across API/UI payloads.
+        if "registered" in normalized and "created_at" not in normalized:
+            normalized["created_at"] = normalized["registered"]
+        if "created_at" in normalized and "registered" not in normalized:
+            normalized["registered"] = normalized["created_at"]
         return normalized
     if isinstance(value, list):
         return [_normalize_formula_scope(item) for item in value]

From dbdbfadbd7ae58c6f8f1d7a5c3bb4a8fdeb1d6b6 Mon Sep 17 00:00:00 2001
From: akira69 <akira69@gmail.com>
Date: Mon, 16 Mar 2026 14:28:09 -0500
Subject: [PATCH 3/3] style: Apply ESLint, Prettier, and Ruff formatting fixes

---
 .../pages/settings/formulaFieldsSettings.tsx  | 329 +++++++++++-------
 spoolman/derived_fields.py                    |   8 +-
 2 files changed, 202 insertions(+), 135 deletions(-)

diff --git a/client/src/pages/settings/formulaFieldsSettings.tsx b/client/src/pages/settings/formulaFieldsSettings.tsx
index 952451e83..5e261841b 100644
--- a/client/src/pages/settings/formulaFieldsSettings.tsx
+++ b/client/src/pages/settings/formulaFieldsSettings.tsx
@@ -10,7 +10,6 @@ import {
   PlusOutlined,
   QuestionCircleOutlined,
   WarningOutlined,
-  CopyOutlined,
 } from "@ant-design/icons";
 import { useTranslate } from "@refinedev/core";
 import {
@@ -215,9 +214,7 @@ function resolveColorLuminance(color: string): number | null {
   if (hexMatch) {
     const hex = hexMatch[1];
     const value =
-      hex.length === 3 || hex.length === 4
-        ? `${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}`
-        : hex.slice(0, 6);
+      hex.length === 3 || hex.length === 4 ? `${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}` : hex.slice(0, 6);
     const r = parseInt(value.slice(0, 2), 16);
     const g = parseInt(value.slice(2, 4), 16);
     const b = parseInt(value.slice(4, 6), 16);
@@ -421,11 +418,22 @@ function randomFloatSampleValue(): number {
 
 // Randomize datetime sample times so date-diff previews surface fractional values by default.
 function randomTwoDigitSampleValue(maxExclusive: number): string {
-  return Math.floor(Math.random() * maxExclusive).toString().padStart(2, "0");
+  return Math.floor(Math.random() * maxExclusive)
+    .toString()
+    .padStart(2, "0");
 }
 
 function randomIsoDatetimeSampleValue(baseDate: string): string {
-  return baseDate + "T" + randomTwoDigitSampleValue(24) + ":" + randomTwoDigitSampleValue(60) + ":" + randomTwoDigitSampleValue(60) + "Z";
+  return (
+    baseDate +
+    "T" +
+    randomTwoDigitSampleValue(24) +
+    ":" +
+    randomTwoDigitSampleValue(60) +
+    ":" +
+    randomTwoDigitSampleValue(60) +
+    "Z"
+  );
 }
 
 function randomOrderedIntegerRangeSampleValue(): [number, number] {
@@ -575,7 +583,11 @@ function inferExpressionJsonType(node: unknown): FormulaResultTypeHint {
     return "number";
   }
 
-  if (["date_only", "time_only", "today", "cat", "concat", "replace", "trim", "upper", "lower", "left", "right"].includes(operator)) {
+  if (
+    ["date_only", "time_only", "today", "cat", "concat", "replace", "trim", "upper", "lower", "left", "right"].includes(
+      operator,
+    )
+  ) {
     return "text";
   }
 
@@ -669,13 +681,14 @@ export function FormulaFieldsSettings() {
     () => ({
       display: "grid",
       // Keep references dense while predictable: 4 columns on desktop, 3/2 on medium widths, 1 on mobile.
-      gridTemplateColumns: screens.lg || screens.xl || screens.xxl
-        ? "repeat(4, minmax(0, 1fr))"
-        : screens.md
-          ? "repeat(3, minmax(0, 1fr))"
-          : screens.sm
-            ? "repeat(2, minmax(0, 1fr))"
-            : "repeat(1, minmax(0, 1fr))",
+      gridTemplateColumns:
+        screens.lg || screens.xl || screens.xxl
+          ? "repeat(4, minmax(0, 1fr))"
+          : screens.md
+            ? "repeat(3, minmax(0, 1fr))"
+            : screens.sm
+              ? "repeat(2, minmax(0, 1fr))"
+              : "repeat(1, minmax(0, 1fr))",
       gap: 6,
     }),
     [screens.lg, screens.md, screens.sm, screens.xl, screens.xxl],
@@ -781,10 +794,11 @@ export function FormulaFieldsSettings() {
           mixBlendMode: "normal",
         },
         // Force one consistent drawn selection color for both focused and blurred states.
-        ".cm-selectionBackground, .cm-selectionLayer .cm-selectionBackground, &.cm-focused .cm-selectionBackground, &.cm-focused .cm-selectionLayer .cm-selectionBackground": {
-          backgroundColor: `${selectionColor} !important`,
-          borderRadius: 2,
-        },
+        ".cm-selectionBackground, .cm-selectionLayer .cm-selectionBackground, &.cm-focused .cm-selectionBackground, &.cm-focused .cm-selectionLayer .cm-selectionBackground":
+          {
+            backgroundColor: `${selectionColor} !important`,
+            borderRadius: 2,
+          },
         // Keep native browser selection transparent so it doesn't override with platform colors.
         ".cm-content ::selection, .cm-line ::selection, .cm-line > span::selection, .cm-content *::selection": {
           backgroundColor: "transparent !important",
@@ -833,10 +847,7 @@ export function FormulaFieldsSettings() {
     ],
     [t],
   );
-  const keyLooksLikeReservedToken = useMemo(
-    () => RESERVED_DERIVED_KEY_NAMES.has(derivedKeyValue),
-    [derivedKeyValue],
-  );
+  const keyLooksLikeReservedToken = useMemo(() => RESERVED_DERIVED_KEY_NAMES.has(derivedKeyValue), [derivedKeyValue]);
 
   const sampleValuesPlaceholder = SAMPLE_VALUE_PLACEHOLDERS[selectedEntityType];
 
@@ -1021,7 +1032,9 @@ export function FormulaFieldsSettings() {
     // tokens that can't accept that selected reference kind. Clearing/completing pending insert
     // resets all helper tokens back to normal.
     if (pendingJsonHelperInsert?.selectedOperands.length) {
-      const selectedReference = pendingJsonHelperInsert.selectedOperands.find((operand) => operand.kind === "reference");
+      const selectedReference = pendingJsonHelperInsert.selectedOperands.find(
+        (operand) => operand.kind === "reference",
+      );
       if (!selectedReference) {
         return null;
       }
@@ -1100,17 +1113,17 @@ export function FormulaFieldsSettings() {
     <div style={{ display: "grid", gap: 6 }}>
       {operatorGroups.map((group) => {
         const compactTitle =
-          group.key === "logical"
-            ? (
-              <>
-                {t("settings.formula_fields.formula.json_builder.operator_compact.logical_top")}
-                <br />
-                {t("settings.formula_fields.formula.json_builder.operator_compact.logical_bottom")}
-              </>
-            )
-            : group.key === "comparison"
-              ? t("settings.formula_fields.formula.json_builder.operator_compact.comparison")
-              : t("settings.formula_fields.formula.json_builder.operator_compact.math");
+          group.key === "logical" ? (
+            <>
+              {t("settings.formula_fields.formula.json_builder.operator_compact.logical_top")}
+              <br />
+              {t("settings.formula_fields.formula.json_builder.operator_compact.logical_bottom")}
+            </>
+          ) : group.key === "comparison" ? (
+            t("settings.formula_fields.formula.json_builder.operator_compact.comparison")
+          ) : (
+            t("settings.formula_fields.formula.json_builder.operator_compact.math")
+          );
         const operatorGridColumns = group.key === "logical" ? "repeat(2, max-content)" : "repeat(3, max-content)";
         const labelColumnWidth = group.key === "logical" ? 90 : 78;
         return (
@@ -1135,7 +1148,7 @@ export function FormulaFieldsSettings() {
                 justifyContent: "start",
               }}
             >
-              {group.operators.map((operator) => (
+              {group.operators.map((operator) =>
                 (() => {
                   const tokenId = `operator-${group.key}-${operator}`;
                   const isHovered = hoveredTokenId === tokenId;
@@ -1158,17 +1171,29 @@ export function FormulaFieldsSettings() {
                         transition: "all 120ms ease-out",
                       }}
                       onMouseEnter={interactive && !disabled ? () => setHoveredTokenId(tokenId) : undefined}
-                      onMouseLeave={interactive && !disabled ? () => setHoveredTokenId((current) => (current === tokenId ? null : current)) : undefined}
+                      onMouseLeave={
+                        interactive && !disabled
+                          ? () => setHoveredTokenId((current) => (current === tokenId ? null : current))
+                          : undefined
+                      }
                       onClick={interactive && !disabled ? () => insertExpressionJsonOperator(operator) : undefined}
                     >
                       {operator}
                     </Typography.Text>
                   );
-                })()
-              ))}
+                })(),
+              )}
             </div>
             <Typography.Text type="secondary">
-              <strong style={{ lineHeight: 1.1, fontSize: "0.92em", whiteSpace: "nowrap", textAlign: "right", display: "block" }}>
+              <strong
+                style={{
+                  lineHeight: 1.1,
+                  fontSize: "0.92em",
+                  whiteSpace: "nowrap",
+                  textAlign: "right",
+                  display: "block",
+                }}
+              >
                 {compactTitle}
               </strong>
             </Typography.Text>
@@ -1184,11 +1209,7 @@ export function FormulaFieldsSettings() {
   // helper snippet with those references. Respects helper constraints: insert_mode (none/single/multiple),
   // reference_count (how many fields the helper needs), value_kind (type checks for compatibility).
   // Disabled helpers show tooltips explaining why (e.g., "no numeric fields available for math helper").
-  const renderHelperTokenCategory = (
-    groupKey: string,
-    interactive: boolean,
-    compact = false,
-  ) => {
+  const renderHelperTokenCategory = (groupKey: string, interactive: boolean, compact = false) => {
     const group = helperGroupByKey[groupKey];
     if (!group || group.helpers.length === 0) {
       return null;
@@ -1216,7 +1237,11 @@ export function FormulaFieldsSettings() {
               transition: "all 120ms ease-out",
             }}
             onMouseEnter={interactive && !disabledReason ? () => setHoveredTokenId(tokenId) : undefined}
-            onMouseLeave={interactive && !disabledReason ? () => setHoveredTokenId((current) => (current === tokenId ? null : current)) : undefined}
+            onMouseLeave={
+              interactive && !disabledReason
+                ? () => setHoveredTokenId((current) => (current === tokenId ? null : current))
+                : undefined
+            }
             onClick={interactive && !disabledReason ? () => insertExpressionJsonHelper(helper) : undefined}
           >
             {helper.name}
@@ -1502,9 +1527,9 @@ export function FormulaFieldsSettings() {
     }
 
     const snippet = {
-      [pendingHelperDefinition.name]: selectedOperands.slice(0, requiredReferenceCount).map((operand) => (
-        operand.kind === "reference" ? { var: operand.value } : { [operand.value]: [] }
-      )),
+      [pendingHelperDefinition.name]: selectedOperands
+        .slice(0, requiredReferenceCount)
+        .map((operand) => (operand.kind === "reference" ? { var: operand.value } : { [operand.value]: [] })),
     };
     // Insert ready-to-parse JSON Logic objects so users can build expressions without memorizing
     // raw AST syntax. Pending helper operands may be refs or helper calls like today().
@@ -1515,7 +1540,12 @@ export function FormulaFieldsSettings() {
   const insertExpressionJsonHelper = (helper: FormulaHelperDefinition) => {
     // Treat today() as a valid date-diff operand while a pending helper is collecting
     // operands, so clicks produce one combined snippet instead of standalone {"today":[]}.
-    if (pendingHelperDefinition && helper.insert_mode === "none" && helper.name === "today" && pendingHelperDefinition.category === "date_diff") {
+    if (
+      pendingHelperDefinition &&
+      helper.insert_mode === "none" &&
+      helper.name === "today" &&
+      pendingHelperDefinition.category === "date_diff"
+    ) {
       const pendingState = pendingJsonHelperInsert;
       if (!pendingState) {
         return;
@@ -1530,9 +1560,9 @@ export function FormulaFieldsSettings() {
         return;
       }
       const snippet = {
-        [pendingHelperDefinition.name]: selectedOperands.slice(0, requiredReferenceCount).map((operand) => (
-          operand.kind === "reference" ? { var: operand.value } : { [operand.value]: [] }
-        )),
+        [pendingHelperDefinition.name]: selectedOperands
+          .slice(0, requiredReferenceCount)
+          .map((operand) => (operand.kind === "reference" ? { var: operand.value } : { [operand.value]: [] })),
       };
       // Allow date-diff helpers to consume dynamic today() as an operand instead of inserting it standalone.
       insertExpressionJsonSnippet(JSON.stringify(snippet, null, 2));
@@ -1706,9 +1736,14 @@ export function FormulaFieldsSettings() {
       });
 
       messageApi.success(
-        t(editingDerivedKey ? "settings.formula_fields.formula.messages.updated" : "settings.formula_fields.formula.messages.created", {
-          name: values.name,
-        }),
+        t(
+          editingDerivedKey
+            ? "settings.formula_fields.formula.messages.updated"
+            : "settings.formula_fields.formula.messages.created",
+          {
+            name: values.name,
+          },
+        ),
       );
       closeDerivedModal();
     } catch (errInfo) {
@@ -1742,11 +1777,7 @@ export function FormulaFieldsSettings() {
       const referenceKind = referenceKindByName[reference] || "unknown";
       // Seed new sample keys with type-aware defaults so previews work immediately
       // and users can adjust values instead of building sample JSON from scratch.
-      const defaultValue = getSampleDefaultValue(
-        referenceKind,
-        reference,
-        configuredFieldByReference[reference],
-      );
+      const defaultValue = getSampleDefaultValue(referenceKind, reference, configuredFieldByReference[reference]);
       if (insertReferencePathIfMissing(mergedSampleValues, reference, defaultValue)) {
         insertedReferences.push(reference);
         trackedAutoReferences.add(reference);
@@ -1762,49 +1793,56 @@ export function FormulaFieldsSettings() {
 
   // Execute preview with request sequencing so stale async responses never overwrite
   // newer editor state while users are typing quickly.
-  const runPreview = useCallback(async (showMessageOnError: boolean) => {
-    const requestId = previewRequestRef.current + 1;
-    previewRequestRef.current = requestId;
-    try {
-      const sampleValues = parseSampleValues((derivedForm.getFieldValue("sample_values") as string | undefined) || "{}");
-      const expressionJson = parseExpressionJson(derivedForm.getFieldValue("expression_json") as string | undefined);
-      if (!expressionJson) {
-        throw new Error(t("settings.formula_fields.formula.expression_json_required"));
-      }
-      // Preview uses sample JSON only as a sandbox for validating formulas before they are exposed
-      // on show/list/template surfaces.
-      const preview = await previewDerivedField.mutateAsync({
-        expression_json: expressionJson,
-        sample_values: sampleValues,
-      });
+  const runPreview = useCallback(
+    async (showMessageOnError: boolean) => {
+      const requestId = previewRequestRef.current + 1;
+      previewRequestRef.current = requestId;
+      try {
+        const sampleValues = parseSampleValues(
+          (derivedForm.getFieldValue("sample_values") as string | undefined) || "{}",
+        );
+        const expressionJson = parseExpressionJson(derivedForm.getFieldValue("expression_json") as string | undefined);
+        if (!expressionJson) {
+          throw new Error(t("settings.formula_fields.formula.expression_json_required"));
+        }
+        // Preview uses sample JSON only as a sandbox for validating formulas before they are exposed
+        // on show/list/template surfaces.
+        const preview = await previewDerivedField.mutateAsync({
+          expression_json: expressionJson,
+          sample_values: sampleValues,
+        });
 
-      if (requestId !== previewRequestRef.current) {
-        return;
-      }
-      setPreviewText(formatPreviewValue(preview.result));
-      setPreviewErrorText(null);
-    } catch (errInfo) {
-      if (requestId !== previewRequestRef.current) {
-        return;
-      }
-      setPreviewText(null);
-      if (errInfo instanceof Error) {
-        setPreviewErrorText(errInfo.message);
-      } else {
-        setPreviewErrorText(t("settings.formula_fields.formula.preview.error_fallback"));
-      }
-      if (showMessageOnError && errInfo instanceof Error) {
-        messageApi.error(errInfo.message);
+        if (requestId !== previewRequestRef.current) {
+          return;
+        }
+        setPreviewText(formatPreviewValue(preview.result));
+        setPreviewErrorText(null);
+      } catch (errInfo) {
+        if (requestId !== previewRequestRef.current) {
+          return;
+        }
+        setPreviewText(null);
+        if (errInfo instanceof Error) {
+          setPreviewErrorText(errInfo.message);
+        } else {
+          setPreviewErrorText(t("settings.formula_fields.formula.preview.error_fallback"));
+        }
+        if (showMessageOnError && errInfo instanceof Error) {
+          messageApi.error(errInfo.message);
+        }
       }
-    }
-  }, [derivedForm, messageApi, previewDerivedField, t]);
+    },
+    [derivedForm, messageApi, previewDerivedField, t],
+  );
 
   // Apply one synchronization pass between expression refs and sample JSON.
   // The pass is non-destructive for user-owned keys while still cleaning stale auto-managed refs.
   const syncMissingSampleValueKeys = (showMessageOnError: boolean) => {
     let currentSampleValues: Record<string, unknown>;
     try {
-      currentSampleValues = parseSampleValues((derivedForm.getFieldValue("sample_values") as string | undefined) || "{}");
+      currentSampleValues = parseSampleValues(
+        (derivedForm.getFieldValue("sample_values") as string | undefined) || "{}",
+      );
     } catch (errInfo) {
       if (showMessageOnError && errInfo instanceof Error) {
         messageApi.warning(errInfo.message);
@@ -1813,7 +1851,8 @@ export function FormulaFieldsSettings() {
     }
 
     // Apply additive scaffolding and dead-key pruning without touching user-owned sample keys.
-    const { mergedSampleValues, insertedReferences, removedReferences } = buildSampleValuesWithMissingReferences(currentSampleValues);
+    const { mergedSampleValues, insertedReferences, removedReferences } =
+      buildSampleValuesWithMissingReferences(currentSampleValues);
 
     if (insertedReferences.length === 0 && removedReferences.length === 0) {
       return true;
@@ -1832,7 +1871,7 @@ export function FormulaFieldsSettings() {
       return;
     }
 
-    if (((expressionJsonValue || "").trim()) === "") {
+    if ((expressionJsonValue || "").trim() === "") {
       autoManagedSampleReferencesRef.current.clear();
       const currentSampleValuesRaw = (derivedForm.getFieldValue("sample_values") as string | undefined) || "";
       if (currentSampleValuesRaw.trim() !== "{}") {
@@ -1865,7 +1904,7 @@ export function FormulaFieldsSettings() {
       return;
     }
 
-    if (((expressionJsonValue || "").trim()) === "") {
+    if ((expressionJsonValue || "").trim() === "") {
       setPreviewText(null);
       setPreviewErrorText(t("settings.formula_fields.formula.expression_json_required"));
       return;
@@ -2086,10 +2125,7 @@ export function FormulaFieldsSettings() {
         pagination={false}
         locale={{
           emptyText: (
-            <Empty
-              description={t("settings.formula_fields.formula.empty")}
-              image={Empty.PRESENTED_IMAGE_SIMPLE}
-            />
+            <Empty description={t("settings.formula_fields.formula.empty")} image={Empty.PRESENTED_IMAGE_SIMPLE} />
           ),
         }}
         onRow={(record) => {
@@ -2151,7 +2187,7 @@ export function FormulaFieldsSettings() {
                   "settings.formula_fields.formula.tooltips.key",
                 )}
                 name="key"
-                extra={(
+                extra={
                   <Space direction="vertical" size={2} style={{ width: "100%" }}>
                     <Typography.Text type="secondary">
                       {t("settings.formula_fields.formula.key_usage_help")}:{" "}
@@ -2164,7 +2200,7 @@ export function FormulaFieldsSettings() {
                       </Typography.Text>
                     )}
                   </Space>
-                )}
+                }
                 rules={[
                   { required: true, min: 1, max: 64, pattern: /^[a-z0-9_]+$/ },
                   {
@@ -2199,7 +2235,11 @@ export function FormulaFieldsSettings() {
               </Form.Item>
             </Col>
           </Row>
-          <Form.Item label={t("settings.formula_fields.formula.columns.description")} name="description" rules={[{ max: 512 }]}>
+          <Form.Item
+            label={t("settings.formula_fields.formula.columns.description")}
+            name="description"
+            rules={[{ max: 512 }]}
+          >
             <Input.TextArea autoSize={{ minRows: 2, maxRows: 4 }} />
           </Form.Item>
           <Form.Item
@@ -2255,7 +2295,9 @@ export function FormulaFieldsSettings() {
                   // Validate that all referenced custom fields still exist (prevent silent formula failures after field deletion)
                   const referencedCustomFields = getExtraFieldReferences(parsed);
                   const availableCustomFields = new Set((configuredFields.data || []).map((field) => field.key));
-                  const missingFields = referencedCustomFields.filter((fieldKey) => !availableCustomFields.has(fieldKey));
+                  const missingFields = referencedCustomFields.filter(
+                    (fieldKey) => !availableCustomFields.has(fieldKey),
+                  );
                   if (missingFields.length > 0) {
                     throw new Error(
                       t("settings.formula_fields.formula.missing_references", { references: missingFields.join(", ") }),
@@ -2322,7 +2364,8 @@ export function FormulaFieldsSettings() {
                         // Ignore no-op sync events where CodeMirror re-emits the same text that is
                         // already in the form model. This prevents guided IF/operator state from
                         // being canceled before the user clicks the next required token.
-                        const currentExpressionValue = (derivedForm.getFieldValue("expression_json") as string | undefined) || "";
+                        const currentExpressionValue =
+                          (derivedForm.getFieldValue("expression_json") as string | undefined) || "";
                         if (value === currentExpressionValue) {
                           return;
                         }
@@ -2338,12 +2381,7 @@ export function FormulaFieldsSettings() {
                     />
                   </div>
                   {/* Keep editor action controls anchored under the expression editor. */}
-                  <Flex
-                    justify="flex-end"
-                    align="center"
-                    gap={8}
-                    style={{ marginTop: 4 }}
-                  >
+                  <Flex justify="flex-end" align="center" gap={8} style={{ marginTop: 4 }}>
                     <Tooltip title={t("settings.formula_fields.formula.json_builder.format_tooltip")}>
                       <Button size="small" onClick={() => formatExpressionJson()}>
                         {t("settings.formula_fields.formula.json_builder.format")}
@@ -2419,10 +2457,7 @@ export function FormulaFieldsSettings() {
                 <Tooltip title={t("settings.formula_fields.formula.json_builder.click_to_insert_help")}>
                   <QuestionCircleOutlined style={{ fontSize: "0.9em" }} />
                 </Tooltip>
-                <Link
-                  style={{ fontSize: "0.85em" }}
-                  to="/help#formula-token-groups"
-                >
+                <Link style={{ fontSize: "0.85em" }} to="/help#formula-token-groups">
                   {t("settings.formula_fields.help_links.formula_tokens")}
                 </Link>
                 <Tooltip
@@ -2486,12 +2521,18 @@ export function FormulaFieldsSettings() {
                               />
                             </Tooltip>
                             {pendingHelperHint.allowHelperOnly ? (
-                              <Tooltip title={t("settings.formula_fields.formula.json_builder.insert_without_reference_tooltip")}>
+                              <Tooltip
+                                title={t(
+                                  "settings.formula_fields.formula.json_builder.insert_without_reference_tooltip",
+                                )}
+                              >
                                 <Button
                                   size="small"
                                   type="primary"
                                   onClick={() => insertPendingHelperWithoutReferences()}
-                                  aria-label={t("settings.formula_fields.formula.json_builder.insert_without_reference_tooltip")}
+                                  aria-label={t(
+                                    "settings.formula_fields.formula.json_builder.insert_without_reference_tooltip",
+                                  )}
                                 >
                                   {t("settings.formula_fields.formula.json_builder.helper_only")}
                                 </Button>
@@ -2539,18 +2580,33 @@ export function FormulaFieldsSettings() {
                                   fontWeight: 500,
                                   color: isSelectedForPendingHelper
                                     ? token.colorPrimaryText
-                                    : (!disabledReason && hoveredTokenId === `reference-${reference.value}` ? token.colorWarningText : undefined),
+                                    : !disabledReason && hoveredTokenId === `reference-${reference.value}`
+                                      ? token.colorWarningText
+                                      : undefined,
                                   background:
-                                    !disabledReason && hoveredTokenId === `reference-${reference.value}` ? token.colorWarningBg : undefined,
+                                    !disabledReason && hoveredTokenId === `reference-${reference.value}`
+                                      ? token.colorWarningBg
+                                      : undefined,
                                   borderColor:
                                     !disabledReason && hoveredTokenId === `reference-${reference.value}`
                                       ? token.colorWarningBorder
                                       : undefined,
                                   transition: "all 120ms ease-out",
                                 }}
-                                onMouseEnter={!disabledReason ? () => setHoveredTokenId(`reference-${reference.value}`) : undefined}
-                                onMouseLeave={!disabledReason ? () => setHoveredTokenId((current) => (current === `reference-${reference.value}` ? null : current)) : undefined}
-                                onClick={!disabledReason ? () => insertExpressionJsonReference(reference.value) : undefined}
+                                onMouseEnter={
+                                  !disabledReason ? () => setHoveredTokenId(`reference-${reference.value}`) : undefined
+                                }
+                                onMouseLeave={
+                                  !disabledReason
+                                    ? () =>
+                                        setHoveredTokenId((current) =>
+                                          current === `reference-${reference.value}` ? null : current,
+                                        )
+                                    : undefined
+                                }
+                                onClick={
+                                  !disabledReason ? () => insertExpressionJsonReference(reference.value) : undefined
+                                }
                               >
                                 {reference.label}
                               </Typography.Text>
@@ -2559,13 +2615,20 @@ export function FormulaFieldsSettings() {
                             // do not cause reflow when helper compatibility changes.
                             const content = (
                               <Tooltip title={disabledReason || undefined}>
-                                <span style={{ display: "inline-flex", justifyContent: "center" }}>{referenceToken}</span>
+                                <span style={{ display: "inline-flex", justifyContent: "center" }}>
+                                  {referenceToken}
+                                </span>
                               </Tooltip>
                             );
                             return (
                               <div
                                 key={`reference-cell-${reference.value}`}
-                                style={{ display: "flex", justifyContent: "center", alignItems: "center", minHeight: 24 }}
+                                style={{
+                                  display: "flex",
+                                  justifyContent: "center",
+                                  alignItems: "center",
+                                  minHeight: 24,
+                                }}
                               >
                                 {content}
                               </div>
@@ -2584,10 +2647,7 @@ export function FormulaFieldsSettings() {
             rules={[
               {
                 validator: async (_, value) => {
-                  parseSampleValues(
-                    value,
-                    t("settings.formula_fields.formula.sample_values_invalid"),
-                  );
+                  parseSampleValues(value, t("settings.formula_fields.formula.sample_values_invalid"));
                 },
               },
             ]}
@@ -2597,7 +2657,10 @@ export function FormulaFieldsSettings() {
               <Row gutter={8} align="middle" wrap={!isDesktopLayout}>
                 <Col flex="auto" style={{ minWidth: 0 }}>
                   <Space size={10} wrap>
-                    {labeledField("settings.formula_fields.formula.sample_values", "settings.formula_fields.formula.tooltips.sample_values")}
+                    {labeledField(
+                      "settings.formula_fields.formula.sample_values",
+                      "settings.formula_fields.formula.tooltips.sample_values",
+                    )}
                     <Space size={6}>
                       <Typography.Text type="secondary">Auto-update</Typography.Text>
                       <Switch
@@ -2683,7 +2746,9 @@ export function FormulaFieldsSettings() {
                         <Typography.Text
                           key={`sample-ref-${reference}`}
                           code
-                          style={isDefined ? undefined : { color: token.colorErrorText, borderColor: token.colorErrorBorder }}
+                          style={
+                            isDefined ? undefined : { color: token.colorErrorText, borderColor: token.colorErrorBorder }
+                          }
                         >
                           {reference}
                         </Typography.Text>
diff --git a/spoolman/derived_fields.py b/spoolman/derived_fields.py
index 3f623a45a..0d8c396b5 100644
--- a/spoolman/derived_fields.py
+++ b/spoolman/derived_fields.py
@@ -18,6 +18,7 @@
 
 logger = logging.getLogger(__name__)
 
+
 class DerivedFieldType(Enum):
     """Supported output types for a derived field."""
 
@@ -459,8 +460,7 @@ def _normalize_formula_scope(value: Any) -> Any:
         for key, nested in value.items():
             if key == "extra" and isinstance(nested, dict):
                 normalized[key] = {
-                    extra_key: _parse_extra_field_value(extra_value)
-                    for extra_key, extra_value in nested.items()
+                    extra_key: _parse_extra_field_value(extra_value) for extra_key, extra_value in nested.items()
                 }
                 continue
             normalized[key] = _normalize_formula_scope(nested)
@@ -593,7 +593,9 @@ async def resolve_include_derived_in_api(db: AsyncSession, include_derived: bool
     return default_value
 
 
-async def add_or_update_derived_field(db: AsyncSession, entity_type: EntityType, derived_field: DerivedFieldDefinition) -> None:
+async def add_or_update_derived_field(
+    db: AsyncSession, entity_type: EntityType, derived_field: DerivedFieldDefinition
+) -> None:
     """Create or update a derived field."""
     _validate_expression_payload(derived_field.expression_json)