fix(fields): a text field that declares options reads the option label in its record cell - #28817

Requested by Leehom · project thread

Fixes #28792

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么：文本类字段（text、textarea 等走文本单元格的类型）如果声明了非空的 options，列表和详情里的只读单元格现在显示匹配选项的标签（如 Backlog），不再显示存储值 backlog；存储值不变，匹配不到的值照原样显示，没有 options 的字段完全不变。
• 为什么改：同一个 options 声明，图表维度和分组表头早就按标签显示，只有单元格显示原值，一个声明读出两种样子。席位路线是对齐（enforce），不是禁止声明。
• 风险与回滚：低。只改只读显示，不碰编辑输入、表单、存储和 spec。仓内 platform-objects、examples、平台 apps、plugins、services 以及 hotcrm 实测没有任何非选择类字段声明 options，现有界面零变化。回滚即撤销本 PR。
• 先看：ui/packages/fields/src/index.tsx（TextCellRenderer 的选项分支，和从 SelectCellRenderer 提出来共用的 findDeclaredOption）；ui/packages/fields/src/__tests__/TextCellRenderer.declaredOptions-28792.test.tsx。
• 两分钟验证：pnpm --dir ui exec vitest run packages/fields/src/__tests__/TextCellRenderer.declaredOptions-28792.test.tsx，预期 7/7 通过（main 上两条标签用例红：显示 backlog 而不是 Backlog）。
• 需要你做的：无，席位落地。

What changes

The seam. options is a spec key on every field type (FieldSchema.options). Two faces already honour a declared non-empty list on any type, on purpose: analytics dimension labels (service-analytics dimension-labels.ts, "the condition is the declared list itself, never the field's type") and grid group headers (plugin-grid objectGridGrouping.ts). The read-only text cell ignored it, so text + options: [{ value: 'backlog', label: 'Backlog' }] read backlog in a list or detail cell and Backlog in a chart or group header.

• TextCellRenderer (ui/packages/fields/src/index.tsx). When the field carries a non-empty options array (the same test analytics applies, Array.isArray(options) && options.length > 0) and the stored value is a string or number, the cell draws the matching option's label through core's optionDisplayLabel. The full-text hover title carries the same label. Every type this cell draws gets the same reading (text, textarea, code, qrcode, time, auto_number, the widget faces registered to it, and the fallback for undeclared types).
• Unchanged: the stored value; a value that names no option (reads as itself); a field with no list or an empty list (byte-identical markup, pinned); arrays and expanded records (keep the coerced text, since neither is one option's code); edit inputs and forms (a text field with options stays a free text input); SelectCellRenderer's output.
• One matcher. The select cell's value-to-option match (exact, then case-insensitive) moves out of SelectCellRenderer's body into a module function, findDeclaredOption, which both cells call. No second matcher was written. The grid grouping's matcher lives inside a plugin-grid hook and is not importable from @object-ui/fields.
• Translation follows the select cell: the labels arrive already translated, because every host that hands a cell its field (generateColumns in plugin-grid, DetailSection in plugin-detail) runs translateOptions over a non-empty options list whatever the field's type.
• How options reaches the cell. Through the existing field prop of CellRendererProps; no published prop or type was widened. The per-type metadata (TextFieldMetadata) does not name options, so the cell reads it structurally, (field as { options?: unknown }).options, the way LookupCellRenderer reads its static options, and guards it with Array.isArray.
• Changeset .changeset/28792-text-cell-declared-option-label.md: patch on @object-ui/fields, with both declaration lines.

Clause-② measured: no. The diff touches no packages/spec path, no published export (findDeclaredOption is module-private; TextCellRenderer's signature is unchanged) and no wire shape. It changes what one console cell draws for metadata the spec already accepts. Metadata-protocol: none: no key, accepted value or meaning an author writes moved.

Tests

• Measure first (shipped count). An AST scan (TypeScript compiler API, Field.X({...}) calls and { type: 'X', ... } literals with an options key that is not an empty array literal) over the tree at base c064d3a2:
  • packages/platform-objects: 88 files, 8 options declarations, 0 on a non-option type.
  • examples/**: 161 files, 53 declarations, 0 on a non-option type.
  • packages/apps (account, connector-github, connector-stripe, setup, studio): 16 files, 0 declarations, 0.
  • packages/plugins + packages/services: 773 files, 32 declarations, 0.
  • hotcrm (src/, apps/, at a598256): 302 files, 80 declarations, 0 fields (8 hits are dashboard widgets of type table/area, not fields).
  • Positive control: a fixture with Field.text({ options: [...] }) and { type: 'textarea', options: OPTS } is reported as 2 hits, and a Field.select beside them is not.
  • So the change moves no shipped screen; it lines up the cell for any author who declares the list.
• Red first, at base (the test committed alone as bb5573c2, cell file at base): TextCellRenderer.declaredOptions-28792.test.tsx failed 2 of 7, expected 'backlog' to be 'Backlog' and expected 'in_progress' to be 'In progress' (the textarea case). The five controls were green on base.
• Green at 32dc0196: the file passes 7/7. With it, cell-truncation.test.tsx, formulaFaces.textFace-12357.test.tsx, fieldFaceSeam-13216.test.tsx and select-label-association-e2e.test.tsx: 5 files, 39/39.
• Controls (same file): unmatched other reads other; an empty options: [] reads the stored value; a field with no options renders exactly span.block.max-w-full.truncate with title="backlog" and text backlog; SelectCellRenderer with the same list still reads Backlog; TextField (the edit input) of a text field with options holds the raw backlog.
• Full @object-ui/fields suite at 7e05456b: pnpm --dir ui exec vitest run --maxWorkers=2 packages/fields/: Test Files 292 passed, 1 skipped (293); Tests 4399 passed, 7 skipped (4406). Lock VERDICT command-exit 0.
• Type-check: ui/packages/fields pnpm run type-check (tsc --noEmit && tsc -p tsconfig.test.json; the test config includes src/**/*.test.tsx, so the new test is compiled): exit 0, after building the @object-ui/fields^... closure.
• eslint on the two changed source files: 0 errors (152 warnings, all react-refresh/only-export-components on the barrel's existing exports; the new function is not exported).

Acceptance notes

• Read-only form face not aligned (out of scope by the route). TextField's readonly branch (a read-only form field, not the cell) still prints the stored value. The order put edit inputs and forms out of scope; DetailSection's read-only rows draw through the cell and do align. A record view whose read-only face is the form widget would still read backlog. Noted, not filed: no shipped field declares the list (count above).
• Case-insensitive match. Reusing the select matcher means a stored BACKLOG names the backlog option in the cell, as it does in a select cell; analytics and grid grouping match exactly, so that value reads Backlog in the cell and BACKLOG in a group header. Same split the select cell already has; noted, not filed.
• Not touched, per the order: authoring lint, analytics, grouping, and sys_notification.topic.

Verification

• Overlap re-read before opening: the 26 open PRs on objectstack-ai/objectstack at 21:2x UTC; every code PR's head was fetched and diffed against its merge base. None touches ui/packages/fields/src/index.tsx; the only one touching ui/packages/fields/ is the Dependabot group bump (chore(deps)(deps-dev): Bump the development-dependencies group with 2 updates #28499, package.json only).
• origin/main moved from c064d3a2 to 70bf4343 while this ran (31 files); none under ui/packages/fields/ or ui/packages/core/src/evaluator/, so the branch was not merged forward.

Generated by Claude Code