Add lookup columns to table views

Merged
FE
14h ago
+1463-242

Front end for lookup columns (#30472). A lookup column shows one field of the record a many-to-one relation points to, e.g. Company › Address on People. You add it from the + header menu: open a relation, then pick one of the related object's fields, as in the advanced filter. Behind IS_LOOKUP_COLUMNS_ENABLED (on in the dev seed).

Column names can't be changed: the label is always "Relation › Field".

Changes

  • Picking a lookup: in the + header menu, a many-to-one relation opens a sub-page of the related object's fields: searchable, its own fields before system fields, no relations. It opens even when the relation column is already shown; when that column is hidden, the sub-page also offers the relation itself first.
  • Saving: useChangeRecordFieldVisibility (what + already uses) gets addLookupRecordField, which adds a non-canonical record field with relationTargetFieldMetadataId at the end of the table. useSaveCurrentViewFields now passes isCanonical and relationTargetFieldMetadataId on create.
  • Lookup target: recordFieldLookupTargetFamilySelector, keyed by the relation field and the looked-up field, resolves the related object and the looked-up field's definition, and reads the feature flag. The cell, header, header menu and footer use it through useRecordFieldLookupTarget. With the flag off, a lookup column renders, loads and aggregates as its plain relation. RecordIndexContext is unchanged.
  • Query and store: the table query adds each looked-up field inside its relation selection. The table loaders (first load, page fetch, grouped) also store the related records of the relations behind visible lookup columns (getRecordsWithLookupRelatedRecords, with names from useGetLookupRelationFieldNames through the same flag gate), so a lookup cell reads its related record by id. Other fields, JSON included, are never read, and with the flag off the rows are stored unchanged. The table reloads when a visible lookup column's relation changes.
  • Cell: one way to build the field context. RecordTableCellFieldContextGeneric takes a target (record, object, field, read-only state, restricted fields). The plain cell passes the row; RecordTableCellLookupFieldContext resolves the related record and passes it. Updates go through the table's updater (RecordTableUpdateContext), which now takes the target object's name, so clear and toggle work on lookup cells. The cell is read-only when there is no related record, the row or table is read-only, the field is restricted, or the user can't update it. A target the user can't read shows as forbidden.
  • Header and menus: the header reads "Relation › Field" with the looked-up field's icon and description. Filter in a lookup column's header filters on the looked-up field (Company → Name), merged in from #30653. Sort and footer totals stay off here: sort needs a relation target on view sorts (#30657, #30661), and a total would count a related record once per row. CSV export leaves extra columns out.
  • Not included: live updates when another user edits a related record. Listening to the whole related object is the wrong scope; the follow-up is twentyhq/core-team-issues#3201.

Stack

Lookup columns show one field of the record a many-to-one relation points to (Company › Address on People); aggregate columns show a count or sum over a one-to-many relation (People › Count on Companies). Each PR targets the one it builds on; retarget it to main once that one merges.

Size counts changed lines outside tests and generated files: S < 300, M 300–800, L > 800.

PRWhat it doesSizeCodeTests / generatedBuilds on
#30472Server: a view field can show one field of its related record (relationTargetFieldMetadataId)M+401 −39+552 −3merged into main
#30450Server: lookup columns in the view field AI toolsS+32+152main
#30348Front: tables handle several columns of one fieldS+289 −70+193merged into main
#30439 👈Front: lookup columns, added from the + menuL+839 −143+191 −29main
#30653Front: filter a lookup column from its headerS+131 −65+45merged into this PR
#30657Server: viewSort.relationTargetFieldMetadataIdM+301 −22+572 −4main
#30661Front: sort a lookup column from its headerS+75 −19+89 −4this PR + #30657
#30482Server + front: aggregate columns (count, sum, avg, min, max)L+1200 −268+1725 −122#30439

Independent of this stack: #30347 (nested one-to-many filter / orderBy / first) and #30485 (upsertViewWidget keeps omitted filter group fields and clears them on null), both on main.

Testing

  • Unit: getRecordsWithManyToOneRelatedRecords, getRecordFieldColumnHeader, getLookupTargetFieldMetadataItems, addLookupTargetsToRecordGqlFields, plus the record-table, record-field, record-store, record-column-lookup, views, navigation-menu-item and object-metadata suites (216 suites, 961 tests).
  • Browser check on the dev seed, on the latest commit:
    • People: + → Company → Employees, then + → Company → Name, adds both columns at the end without a reload; they are saved as non-canonical view fields with their target.
    • Editing Company › Employees in place updates both rows of that company and survives a reload; Backspace clears it.
    • Companies: editing and clearing a plain Employees cell still persists.
    • From the previous round, unchanged by this one: changing a person's company updates its lookup cells; lookup cells are filled on every page down to the last of 1,200 people and in every group of a grouped Opportunities table.
  • Front typecheck and oxlint.

Screenshots

In the + menu, a relation opens a sub-page:

Plus menu

Plus menu, Company fields

Company › Address and Company › Domain Name after a reload (from the previous round; the columns now go at the end of the table):

Lookup columns


Generated by Claude Code