fix(fields): a formula reads one stored value the same in the form and in the cell (objectui#11748)

.changeset/11748-formula-faces.md

@@ -0,0 +1,19 @@
+---
+'@object-ui/fields': patch
+'@object-ui/types': patch
+---
+
+A formula reads the same in a read-only form and in a table cell (objectui#11748).
+
+The read-only form face (`FormulaField`) and the table cell (`FormulaCellRenderer`) formatted a formula's value separately, so one stored value read two ways. The form printed a number raw or with two fixed decimals, in monospace (`200000`, `200000.00`), where the cell read `200,000`. The cell printed a declared boolean or date raw (`true`, `2026-07-04`), where the form read `Yes` and `Jul 4`.
+
+Both faces now use one rule. The type is the field's declared `returnType`. With no `returnType`, a JS number is a number and any other value is text. No type is inferred from the expression. Each type is drawn the way the matching field type draws it:
+
+- **number**: formatted in the viewer's locale, at the width a declared `scale` gives, as on a number field. `200000` reads `200,000` in en-US and zh-CN in both faces; two fixed decimals are no longer added.
+- **boolean**: the language's Yes / No word in both faces (`是` / `否` in zh-CN). The cell no longer prints `true`. Only a JS boolean counts, as on a boolean field. A non-boolean value draws the empty-value mark, where the form used to read `Yes` for the string `'false'`.
+- **date**: the date field's read-only face, `formatDate`'s default (`Jul 4`, or `Jul 4, 2020` outside the current year), in both faces. The cell does not use the date cell's relative face (`Today`, `2 days ago`), because the form has no relative face to match. An unparsable value draws the empty-value mark.
+- **text**: the value in monospace, as before. The form now prints it the way the cell does: an empty string or empty list draws the empty-value mark, where the form drew a blank, and an expanded record reads its name, where the form printed `[object Object]`.
+
+objectui#11683 changed the cell for numbers only and left a declared boolean or date as it was. This change converts both.
+
+No export, prop or language-pack key is added. The `returnType` doc comments in `@object-ui/types`, on `FormulaFieldMetadata` and on the form field, now describe this rule for both faces in place of the retired two-decimal face.

content/docs/fields/formula.mdx

@@ -50,12 +50,20 @@ they are runtime widget props. See [Field Widget Props](/docs/fields/widget-prop
 
 ## Return Types
 
-The formula field formats values by `returnType`:
+The formula field draws its value by `returnType`. The form and the table cell
+read the same rule, so one stored value reads the same in both:
 
-- **number**: Displays with two decimal places
-- **boolean**: Displays as Yes/No
-- **date**: Displays the formatted date
-- **text**: Displays as a string (also the default when `returnType` is absent)
+- **number**: Formatted as a number field formats it, in the viewer's display
+  locale and at the width a `scale` on the field sets (`200000` reads `200,000`
+  in en-US)
+- **boolean**: The UI language's Yes / No word; a value that is not a JS boolean
+  reads as empty
+- **date**: The date field's read-only face (`2020-07-04` reads `Jul 4, 2020` in
+  en-US), in the table cell too: it does not use the date cell's relative style
+- **text**: The value as text, in a monospace font
+
+With no `returnType`, a JS number is drawn as a number and any other value as
+text. Nothing is inferred from the expression.
 
 ## Formula Examples
 
@@ -82,12 +90,15 @@ expression: 'daysBetween(record.start_date, record.end_date)'
 
 ## Cell Renderer
 
-In tables/grids, displays with monospace font:
+In tables/grids, `FormulaCellRenderer` draws the value by the same rule as the
+form (see Return Types above). Only text is drawn in a monospace font. A null or
+empty value renders an em-dash.
 
 ```ts
 import { FormulaCellRenderer } from '@object-ui/fields';
 
-// Renders computed value in monospace font
+// <FormulaCellRenderer value={200000} field={field} /> with no returnType
+// renders the number cell's text: 200,000 (en-US)
 ```
 
 ## Backend Implementation

content/docs/fields/summary.mdx

@@ -129,7 +129,7 @@ In tables/grids, a `summary` value is rendered by the formula cell renderer —
 import { FormulaCellRenderer } from '@object-ui/fields';
 
 // <FormulaCellRenderer value={15750.5} field={field} /> renders the computed
-// value as monospace text: 15750.5
+// value as a number, through the number cell: 15,750.5 (en-US), not monospace
 // A null or empty value renders an em-dash instead.
 ```