feat(settings): Create Extra Fields by Formula via built-in JSON editor

[akira69]

Summary

Adds Formula Extra Fields as a reviewer-facing Settings workflow for authoring derived values from JSON Logic without storing duplicated source data.

betterbugs_recording.webm

What Changed

• Added a distinct Formula Extra Fields section in Extra Fields settings with JSON Logic editing, token insertion, sample-value preview, and save/edit/delete flows.
• Kept display targeting split by surface (Show, List, Template) and API exposure split by field-level include_in_api, returned under derived.*.
• Tightened formula/reference handling so invalid references fail preview/save clearly, referenced extra fields cannot be deleted, and referenced custom fields surface in Settings via Referenced In.
• Brought the frontend reference token list into parity with the backend contract for spool formulas, including nested filament/vendor references such as filament.color_hex.

Screenshots

Create/edit formula field flow

• New Formula Extra Fields section under Extra Fields Settings

- Formula Extra Field Edit Page - Expandable sections for Operators, Helper Functions, and Field References - Type-aware clickable functions to fill JSON

Editor + Help UX

• Dark-mode multi-line selection visibility in the JSON editor

- Aligned help/settings documentation with formula-focused guidance and terminology

Template/List/API Integration examples

• Template usage example using {derived.your_key}

• API response snippet with derived payload

Testing Performed

• ppr 885
• uv run ruff check spoolman/derived_fields.py spoolman/extra_fields.py spoolman/api/v1/field.py spoolman/api/v1/spool.py spoolman/api/v1/filament.py spoolman/api/v1/vendor.py spoolman/formula_references.py tests_integration/tests/fields/test_derived.py tests_integration/tests/fields/test_derived_api.py
• cd client && ./node_modules/.bin/eslint src/pages/settings/extraFieldsSettings.tsx src/pages/settings/formulaFieldsSettings.tsx src/utils/formulaFields.ts src/utils/queryFields.ts
• cd client && VITE_APIURL=/api/v1 npm run build
• PATH=.venv/bin:$PATH python - <<'PY' direct API validation against http://localhost:9885/api/v1
  • previewed date/text/hue formulas
  • verified invalid-reference save/preview failures
  • verified include_in_api is independent from UI surfaces and returned under derived.*
  • verified referenced extra fields cannot be deleted and extra-field type changes stay blocked
  • verified non-formula extra fields still round-trip normally
• $HOME/.codex/skills/playwright/scripts/playwright_cli.sh open http://localhost:9885/settings/extra/spool --headed
• $HOME/.codex/skills/playwright/scripts/playwright_cli.sh snapshot
• $HOME/.codex/skills/playwright/scripts/playwright_cli.sh click ... / fill ... / eval ... / run-code "$CODE" focused browser validation against http://localhost:9885
  • created usage_delta from Settings, used operator/reference token insertion, previewed 200, saved it, and reopened it for editing
  • created registered_date from Settings, used helper/reference insertion, previewed 2026-03-01, and saved it
  • verified nested spool references now appear in the token list, including filament.color_hex
  • verified Referenced In updates to 1 formula field and referenced custom-field delete is disabled in Settings
  • verified JSON editor backgrounds switch between light (rgb(255, 255, 255)) and dark (rgb(20, 20, 20)) themes
  • verified show page renders Usage Delta = 200, Color Hue = 120, Finish Label = Finish: matte, and existing custom fields still render
  • verified Hide Columns toggles the Usage Delta list column both directions (0 -> 1, 1 -> 0, restored to visible)
  • verified Settings delete flow removes Color Hue

Test Checklist

• Settings page includes a distinct Formula Extra Fields section
• Create/edit/save/reopen formula extra fields from Settings
• Operator/helper/field-reference token insertion works for reviewer-facing authoring flows
• Preview updates with sample values for arithmetic/date helpers
• Show-surface formula fields render on the spool detail page
• List-surface formula fields render and participate in Hide Columns
• API derived.* output respects field-level include_in_api independently of UI surfaces
• Referenced extra fields are surfaced in Settings and cannot be deleted while formulas depend on them
• Existing non-formula custom fields still behave normally
• Formula delete flow works from Settings

Remaining Manual Check

• Full print-layout template-editor interaction in /spool/print was only partially exercised. The selection flow was reached, but I did not complete a stable browser assertion against the final template text editor itself in this pass.

[akira69]

Putting this PR back into draft while I rework the formula-field authoring UI in my fork first.

Current issue: the flat field-reference picker gets too cluttered once related filament.* / vendor.* references are exposed.

Follow-up work is moving to akira69#13 so I can iterate on a grouped/searchable/collapsible reference-picker approach before deciding what should come back here.