Class SafeExpressionField

A foundry.data.fields.StringField whose value is a SafeExpression source string — a formula/predicate a GM authors (a Skill's skillBaseFormula, an affliction's duration formula, and so on).

It is a plain StringField on the wire — the value is still just the source text. What it adds is a semantic marker: declaring a field as a SafeExpressionField is how a sheet knows the field holds an expression and warrants the SafeExpression code editor (an edit button that opens openExpressionEditorDialog) rather than a bare text input.

It deliberately does not reject an invalid expression at the schema boundary. By design a malformed formula is stored and surfaced as a warning by the consuming logic (e.g. SkillLogic.computeSkillBase renders a ✕ and an "Invalid expression" hint), so authors can save work-in-progress and fix it later — hard schema rejection would discard it and break that flow. The authoritative validity check (SafeExpression.validateSource) runs live in the editor, where Save stays disabled until the expression is valid.

Using it

Declare it in defineSchema() like any other field, naming the sohl.entity.expr.ExpressionScope its value will be evaluated against:

static override defineSchema(): PlainObject {
    return {
        ...super.defineSchema(),
        // Evaluated by SkillLogic.computeSkillBase against `attr`.
        skillBaseFormula: new SafeExpressionField({ scope: "skill.base" }),
    };
}
Copy

Render it with the shared expressionField Handlebars partial, which draws the formGroup plus the editor button and forwards the declared scope as data-expr-scope — the sheet needs no per-field wiring:

{{> expressionField field=fields.skillBaseFormula
    rootId="skill-sbf" name="system.skillBaseFormula"
    value=system.skillBaseFormula}}
Copy

Then evaluate the stored source against the same scope, so what the editor accepted is exactly what the runtime allows:

const scope = expressionScopes.require("skill.base");
const expr = new SafeExpression({ source }, { parent: this, scope });
const value = expr.evaluate(scope.bind({ attr: this.buildAttrContext() }));
Copy

Options

Every foundry.data.fields.StringField option is accepted (see SafeExpressionField.Options); scope is the only one this class adds.

Only nullable, blank, and initial actually differ from StringField; everything else (required, label, hint, choices, validate, …) behaves exactly as it does there. Override any of them per field — but think twice before reverting nullable/blank, since that pair is what keeps "no formula" a single value instead of two. Both shipped fields (SkillDataModel.skillBaseFormula, AfflictionDataModel.outcomeTrauma) pass nothing but scope.

The scope is what lets the schema tell the sheet which identifiers a formula may use, so the editor's autocomplete and live validation match the call site that actually evaluates it. Before scopes, the sheet template carried a hand-typed data-context="attr" string with nothing tying it to the evaluating code (issue #1142).