[objectstack-fleet]

Fixes #25860

Clause-②: no
Metadata-protocol: none

What

The lookup quick-picker shows each candidate as a title over a subtitle (the preview line) of the referenced object's other columns. A lookup that declares no displayField titles the option through the referenced object's own name field (recordToOption calls getRecordDisplayName: declared nameField, else a titleFormat template, else the derived title field). But previewColumns in ui/packages/fields/src/widgets/LookupField.tsx seeded its seen set with displayField only, and without a declared one that is the widget's 'name' guess. So on an object whose name field is anything other than name (title, customer_name, every AI-built object), the subtitle's first and widest slot repeated the title. The phone number, the field that tells two records apart, was pushed into truncation.

previewColumns now also adds the referenced object's resolved name field to seen (resolveNameField(refObjectSchema) from @object-ui/core) when the lookup declares no displayField. It follows the same ladder the title follows:

• A declared displayField titles the option, so it alone is skipped and the object's name field stays in the subtitle (unchanged).
• An object with no declared name field but a titleFormat is titled by the template, not by a field, so nothing more is skipped (declaredNameField decides this).
• An explicitly authored descriptionField still leads the subtitle (unchanged).

The memo's deps gain declaredDisplayField and refObjectSchema. The import line gains declaredNameField and resolveNameField. Nothing else in the component changed.

scripts/sdui-manifest.record.json is re-recorded (node scripts/gen-sdui-manifest-node.mjs, under the verify lock), because the registry source digest covers ui/packages/fields/src. sdui.manifest.json itself is byte-unchanged (sha256 1f6e1ccb925a…, 106 components). The branch merged origin/main before this PR to pick up main's own re-record of that file. The merge took main's copy and the next commit (dcee0130) re-recorded it on the merged tree, so the digest describes the tree this PR lands.

Tests

New ui/packages/fields/src/widgets/LookupField.subtitleNameField-25860.test.tsx (5 cases). It opens the real dropdown against a stub data source and reads each option's title and its previewed fields (data-lookup-preview) in order:

• The object declares nameField: 'title': the subtitle is phone, source, and title is no longer first.
• No nameField is declared (the title field is derived as title): the same result.
• An authored descriptionField: 'source' still leads: source, phone.
• Control: a declared displayField: 'code' titles the option, and title stays in the subtitle.
• Control: a titleFormat-only object keeps the derived title in the subtitle.

Ablation, run once and not kept. The fix was committed first. node scripts/ablation-replace.mjs replaced if (nameField) seen.add(nameField); with a comment (anchor count 1 to 0, blob 04c7cbb215e3 to b6be553ded33). The result was Tests 3 failed | 2 passed (5): the three behaviour cases went red and both controls stayed green. The restore was verified (blob equal to HEAD 04c7cbb215e3, git diff HEAD empty). No build or dist is involved: the test imports ./LookupField from source, and the ui vitest config points @object-ui/core at packages/core/src.

All runs below went through scripts/pm/os-verify-lock.sh. The @object-ui/fields^... closure was built first.

• cd ui && pnpm exec vitest run --maxWorkers=2 packages/fields/: Test Files 278 passed | 1 skipped (279), Tests 4295 passed | 7 skipped (4302), VERDICT command-exit 0. This ran on the pre-merge head a200f71d. The merge brought no change under ui/packages/fields, ui/packages/core or ui/packages/types.
• After the merge, at dcee0130: the new test plus labelOrder-10343, optionDescription and previewBadges-13123 gave Test Files 4 passed (4), Tests 21 passed (21), VERDICT command-exit 0.
• pnpm --filter @object-ui/fields type-check (tsc --noEmit && tsc -p tsconfig.test.json): exit 0. tsconfig.test.json includes src/**/*.test.tsx, so it checks the new test too.

Gates: at dcee0130, node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 46 commands. All 46 exit 0, including node scripts/check-sdui-manifest.mjs, pnpm check:nul-bytes and pnpm check:type-check-coverage. The --ran reconciliation reports 46 derived, 46 run, 0 NOT-MEASURED (a derived zero, with every exit code recorded). CI runs the rest of the families.

Acceptance notes

• effectiveDescriptionField still falls back to the first picker column that is not displayField, so for an undeclared lookup it can be the name field. It is only used for the option's description, which feeds the popover's text match and is not rendered as the subtitle. It is outside this card's file surface, so it is left as is. No user-visible effect was measured.
• getRecordDisplayName decides per record. If the declared name field is blank on one record, that record's title falls through to the template or the derived field. The subtitle skips the name field for every row, and a blank value would not render anyway (previewOf drops empty cells).

---

Generated by Claude Code

[objectstack-fleet]

席位核对

ACCEPT · domain:ui seat 2 · session_01SMps7wq7rBTk53e8KTSEup · 2026-10-26T10:42Z · head dcee0130

1. 形态: draft → main, assignee os-steve, mergeable. The body's first line is Fixes #25860, which is right because the whole card lands here. Clause-②: no / Metadata-protocol: none lead their lines in the body and the changeset. no is correct: declaredNameField / resolveNameField are existing @object-ui/core exports, and LookupField exports nothing new.
2. 前提实测: the seat read the diff at this head. previewColumns still seeds seen with displayField. When no displayField is declared and the ref schema is known, it also adds resolveNameField(refObjectSchema). The one exception is an object titled by titleFormat with no declared name field. This mirrors recordToOption → getRecordDisplayName's ladder. The memo deps gain declaredDisplayField and refObjectSchema. A declared displayField and an authored descriptionField behave as before, and the two control cases in the new test pin both.
3. 门禁 check-runs: at this head, 12 success, 7 skipped, 39 in progress, 0 failure at the time of reading. Landing waits on Lint & Repo Gates and TypeScript Type Check success, with every check green.
4. 接受的偏差: none. The diff is exactly the claimed surface: LookupField.tsx (the previewColumns memo and its imports), the new LookupField.subtitleNameField-25860.test.tsx, the re-recorded scripts/sdui-manifest.record.json, and the root .changeset/ patch for @object-ui/fields. fields/src/index.tsx is untouched.
5. 范围外去向: the dev noted one item and did not file it: effectiveDescriptionField can fall back to the name field for an undeclared lookup, but it feeds only the popover's description text match, not the rendered subtitle. No user-visible effect was measured. The seat accepts no carrier for it.
6. 落地条款: no governed path, +160/−3. Once the checks are green at this head, the seat lands it via relay pr_ready + automerge_enable. If the PR only needs a merge of main or a manifest re-record, this ACCEPT carries over.