concept(fields): Pre-programmed Common Extra & Formula Fields Library

[akira69]

Concept: Pre-programmed Common Extra & Formula Fields Library

This is a concept draft PR proposing a library of pre-built extra field definitions and formula field templates that users can install with one click instead of building manually.

Status: Concept only. No implementation commits. This branch exists to capture the idea for discussion.
Active field implementation work is in PR #885 (Formula Fields) and PR #878 (Applications Framework).

---

Problem Statement

With PR Donkie#885's Formula Fields and the extra fields system, Spoolman can now express powerful derived values and custom data. But authoring these from scratch requires:

• Knowledge of JSON Logic syntax
• Understanding which field keys to reference
• Time to configure each field

Most users want the same 10–20 fields: PA, flow rate, print temp, lot number, purchase price, drying schedule, etc. These are identical across installations.

This PR proposes: A curated library of ready-to-use definitions that users install rather than author.

---

Concept: "Common Fields" Library

What It Would Be

A settings area (or installable preset pack) offering pre-defined field definitions for:

1. Standard Extra Fields (stored data, no formula): purchase price, lot number, storage location, NFC UID, comment/notes
2. Calibration Fields (stored per-filament): Pressure Advance, flow rate multiplier, print temperature, bed temperature, retraction distance, cooling fan speed
3. Formula Fields (computed/derived): days since last use, remaining weight %, estimated prints remaining, color hex display, cost at current weight
4. Integration Fields (external system IDs): Bambu AMS slot, Bambu filament UID, Klipper variable name, OrcaSlicer profile name

Install Flow (Proposed UX)

Settings → Extra Fields → Browse Common Fields Library
  → [Install] next to each field definition
  → Field appears in Extra Fields list, pre-configured
  → User adjusts defaults if needed

---

Candidate Fields — Calibration (Filament entity)

Requested in Issue #415 (9 comments), Issue #11 (8 comments), PR #855 (SmoothBrainIT calibration wizard):

Key	Type	Label	Notes
pressure_advance	Float	Pressure Advance	PA value (Klipper/Bambu). Donkie#415, #11
flow_rate_multiplier	Float	Flow Rate Multiplier	Extrusion multiplier, e.g. 0.98. #11
print_temp	Integer	Print Temperature (°C)	First layer or general print temp. Donkie#415, Donkie#656
bed_temp	Integer	Bed Temperature (°C)	Recommended bed temp. Donkie#415
retraction_distance	Float	Retraction Distance (mm)	Slicer retraction value. Donkie#415
retraction_speed	Integer	Retraction Speed (mm/s)	Slicer retraction speed. Donkie#415
fan_speed	Integer	Cooling Fan Speed (%)	Default fan speed for this filament. #11
max_volumetric_speed	Float	Max Volumetric Speed (mm³/s)	Bambu/OrcaSlicer MVS value.

Full Calibration Wizard Integration

PR #855 by SmoothBrainIT (community submission) implements a full guided calibration workflow: temperature tower, flow rate, Pressure Advance (Tower auto-compute: PA = step × height; or Pattern/Line direct entry), VFA, Input Shaping, and more. It stores calibration data in new calibration_session and calibration_step DB models.

The Common Fields Library could act as a lightweight alternative for users who just want to store the results without the full wizard: install the calibration fields, enter values manually after running calibrations externally, done.

---

Candidate Fields — Physical Properties (Filament entity)

Requested in Issue #69 (10 comments), Issue #656 (4 comments):

Key	Type	Label	Notes
density	Float	Density (g/cm³)	Auto-suggest by material (PLA=1.24, PETG=1.23, ABS=1.04). Donkie#69, Donkie#656
glass_transition_temp	Integer	Glass Transition Temp (°C)	Tg for storage guidance.
diameter_tolerance	Float	Diameter Tolerance (mm)	e.g. ±0.02.
pigment_loading	Integer	Pigment Loading (%)	Affects flow behavior for color changes.

---

Candidate Fields — Tracking & Inventory (Spool entity)

Requested in Issue #317 (6 comments), Issue #716 (5 comments):

Key	Type	Label	Notes
purchase_price	Float	Purchase Price	Cost paid for this spool. Donkie#317
purchase_date	Datetime	Purchase Date	When purchased.
lot_number	Text	Lot / Batch Number	Manufacturer batch code. Donkie#773
storage_location	Text	Storage Location	Shelf, drawer, bin identifier. Donkie#641
open_date	Datetime	Date Opened	When spool was first unsealed.
print_count	Integer	Estimated Print Jobs	Informal count of jobs using this spool.

---

Candidate Fields — NFC / RFID Integration (Spool entity)

Requested in Issue #799, Issue #776 (16 comments), Issue #723, PR #880 (goeland86 — NFC community submission):

PR #880 adds full NFC support (TigerTag + OpenPrintTag, Web NFC API, Klipper daemon). For users without a full NFC setup, simple extra fields provide the lightweight alternative.

Key	Type	Label	Notes
nfc_uid	Text	NFC Tag UID	Raw tag ID for automation lookup. Donkie#716, Donkie#799
tigertag_id	Text	TigerTag Product ID	TigerTag external DB product ID. PR Donkie#880
openprinttag_uuid	Text	OpenPrintTag Instance UUID	UUID from NFC-V CBOR payload. PR Donkie#880
rfid_uid	Text	RFID Tag UID	For USB RFID reader setups. Donkie#799

---

Candidate Fields — Bambu / Printer Integration (Spool entity)

Requested in Issue #217 (38 comments — most-requested!), Issue #641 (8 comments):

Key	Type	Label	Notes
bambu_ams_slot	Integer	Bambu AMS Slot	Slot number (1–4) in AMS unit. Donkie#217
bambu_ams_unit	Integer	Bambu AMS Unit	AMS hub index for multi-AMS setups. Donkie#217
bambu_filament_id	Text	Bambu Filament Type ID	Internal Bambu type code (e.g. GFA00).
printer_name	Text	Assigned Printer	Which printer this spool is loaded in. Donkie#641
klipper_var_name	Text	Klipper Variable Name	Variable key for Klipper SET_GCODE_VARIABLE.

---

Candidate Formula Fields (derived, not stored)

These build on Formula Fields from PR #885. Requested in Issue #795, Issue #600, Issue #569:

Key	Entity	Label	Formula Logic
remaining_pct	Spool	Remaining %	(remaining_weight / initial_weight) * 100
estimated_prints_remaining	Spool	Est. Prints Remaining	remaining_weight / avg_print_weight (requires avg_print_weight extra field)
days_since_opened	Spool	Days Since Opened	days_between(open_date, now())
cost_per_gram	Spool	Cost per Gram	purchase_price / initial_weight
cost_at_remaining	Spool	Value Remaining	purchase_price * (remaining_weight / initial_weight)
color_hex_display	Filament	Color (hex)	color_hex formatted as #RRGGBB uppercase — Issue #568
days_to_dry	Spool	Days Until Dry	Based on material hygroscopic curve + open_date

---

Implementation Sketch

Option A: JSON preset files (simplest)

A set of .json files in client/public/field-presets/ defining field configs. Settings page loads them and shows an "Install" button per definition.

Option B: Backend preset API

GET /api/v1/field/presets returns available definitions. POST /api/v1/field/from-preset installs one.

Option C: Part of Applications Framework

Common field sets are bundled as applications in PR Donkie#878. Enabling calibration_wizard auto-creates the calibration extra fields. This makes installation contextual — users enable the application, fields follow automatically.

Option C is the most consistent with the Applications Framework direction.

---

Open Questions

1. Conflict handling: What if a user already has an extra field named pressure_advance? Offer to merge, skip, or rename?
2. Default values: Should calibration fields pre-populate with material-type defaults (e.g. PLA PA=0.045)?
3. Formula field auth: Formula fields from PR feat(settings): Create Extra Fields by Formula via built-in JSON editor Donkie/Spoolman#885 require JSON Logic. Should common formula definitions be shipped as pre-validated JSON, or as a guided "formula builder template"?
4. Integration with Applications: Should calibration fields only appear when the calibration_wizard application is enabled?

---

Related Issues & PRs

#	Title	Relevance
Issue #415	Read filament params into printer	Calibration fields
Issue #11	Filament profiles for slicers	PA, flow, retraction fields
Issue #69	Auto-populate density by material	Density field with defaults
Issue #217	Bambu Lab integration	Bambu AMS/UID fields
Issue #641	Spool location/printer tracking	Printer assignment fields
Issue #716	Search by extra fields + Bambu UID	NFC UID, Bambu fields
Issue #776	OpenPrintTag / NFC support	NFC integration fields
Issue #799	RFID support	RFID UID field
Issue #317	Spool quantity / tracking	Purchase price, purchase date
Issue #656	Material defaults (density, temps)	Density, temp defaults
PR #855	Filament calibration wizard	Calibration field set
PR #880	NFC spool identification	NFC/TigerTag/OpenPrintTag fields
PR #885	Formula extra fields	Formula field templates
PR #878	Applications Framework	Option C implementation path