fix(core): $expand user/tree reference columns in list & grid views (not just lookup/master_detail)

[os-zhuang]

The bug

In list / grid (and kanban / calendar / gallery / …) views, reference columns of type user render a bare id (or a "—" placeholder) instead of the related record's name. Record detail views render the same fields correctly.

Example: a grid showing a user-type "technician"/"owner" column shows VYVspo4Eb9vx9AwqV4ThlA4WNt8CeJ80 instead of Dev Admin.

Root cause

List/grid views derive their $expand set from buildExpandFields() in @object-ui/core (packages/core/src/utils/expand-fields.ts). It recognised onlylookup and master_detail field types:

fieldDef.type==='lookup'||fieldDef.type==='master_detail'

So for a user (or tree) reference column the view never requested $expand → the API returned the raw foreign-key id → the cell had no related record to read a display name from → it rendered the raw id / —.

The objectql backend already resolves user through the same expand path as lookup/master_detail (it carries the same reference + id storage). So the gap was purely on the request side, in objectui.

lookup / master_detail columns were already fine (the previous fix added scoped $expand for them) — which is why the bug looked type-specific.

The fix

Extend the expandable-type set to the full reference-bearing set — lookup / master_detail / tree / user — behind a single exported constant + predicate, and route the existing collection logic through it:

exportconstEXPANDABLE_FIELD_TYPES=newSet(['lookup','master_detail','tree','user']);exportfunctionisExpandableFieldType(fieldDef): boolean{/* type ∈ EXPANDABLE_FIELD_TYPES */}

• user is the field type the backend can expand but the frontend wasn't requesting — this is the end-to-end fix.
• tree matches the form layer's DATA_SOURCE_FIELD_TYPES (lookup/master_detail/tree); it's a reference too, so it belongs in the set. Requesting it is harmless and forward-compatible (see follow-up below).

Every $expand caller (list, grid, kanban, calendar, gallery, timeline, gantt, tree, map, detail) routes through buildExpandFields, so this one change fixes them uniformly.

Why only the visible reference columns (unchanged, but the key design point)

buildExpandFields(fields, columns) already intersects with the view's columns, and that's preserved. A list is N rows; expanding a relation per row has a cost, and a list typically shows only 2–3 reference columns. So the default is:

$expand = view columns ∩ reference-typed fields; empty set → omit $expand (original behavior).

Wide objects never pay to expand relations no cell will show. Detail view keeps expanding all reference fields (no columns arg), as before.

This is a pure-function change with the type set extracted as the single source of truth (EXPANDABLE_FIELD_TYPES / isExpandableFieldType), unit-tested for: mixed columns pick out only reference types; non-reference columns never enter $expand; the visible-column intersection; and empty → no $expand.

Verification (framework examples/app-showcase)

Stood up the app-showcase backend + the objectui console against it, on the showcase_field_zoo object (which has one field of every type) via a small grid view exposing the relational columns. Seeded a record with a real user reference.

Column (type)	Before	After
f_lookup (lookup)	Northwind	Northwind
f_master_detail (master_detail)	Website Relaunch	Website Relaunch
f_user (user)	VYVspo4Eb9vx9… (raw id)	Dev Admin ✅
f_owner (user)	VYVspo4Eb9vx9… (raw id)	Dev Admin ✅
f_tree (tree)	—	— (see follow-up)

Confirmed at the API layer too: with $expand=f_user the backend returns f_user: { name: "Dev Admin", … }; without it (today's behavior) it stays a raw id.

Tests / build

• @object-ui/core unit tests: 4683 passed (incl. the extended expand-fields suite — 23 cases).
• @object-ui/plugin-list: 131 passed; @object-ui/core & @object-ui/plugin-grid build clean.

Follow-ups (intentionally NOT in this PR)

• tree display: the frontend now requests$expand for tree, but objectql's expand resolver currently materialises only lookup/master_detail/user, so tree columns still show — until the backend expands tree too. That's a framework change.
• Cross-repo rollout: no .objectui-sha / .framework-sha bumped here. After this merges, it reaches the cloud runtime via a framework .objectui-sha bump (then cloud's own pin) — left to a human to time.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Jun 27, 2026 4:09pm

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	59.0 KB	350 KB
Entry file	index-9dLnz5ka.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	6.87KB	2.47KB
app-shell (runtime-config.js)	4.72KB	1.69KB
app-shell (types.js)	0.01KB	0.04KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	17.16KB	3.44KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	4.79KB	1.88KB
auth (LoginForm.js)	9.55KB	3.36KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.63KB	2.15KB
auth (SocialSignInButtons.js)	8.89KB	3.61KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	24.74KB	6.00KB
auth (createAuthenticatedFetch.js)	3.33KB	1.32KB
auth (index.js)	1.75KB	0.76KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	4.01KB	0.79KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	18.38KB	4.49KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	3.65KB	1.42KB
collaboration (PresenceProvider.js)	2.42KB	0.96KB
collaboration (index.js)	1.25KB	0.53KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	422.37KB	89.87KB
core (index.js)	1.52KB	0.55KB
create-plugin (index.js)	9.28KB	2.98KB
data-objectstack (index.js)	99.69KB	24.89KB
fields (index.js)	164.60KB	39.84KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	2.46KB	0.96KB
i18n (pickLocalized.js)	1.31KB	0.67KB
i18n (provider.js)	5.37KB	1.72KB
i18n (useObjectLabel.js)	21.15KB	4.68KB
i18n (useSafeTranslation.js)	2.68KB	0.98KB
layout (index.js)	36.30KB	10.04KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	4.42KB	1.27KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	1.77KB	0.77KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	5.09KB	1.84KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.46KB	1.03KB
permissions (evaluator.js)	4.00KB	1.23KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.50KB	0.70KB
plugin-ai (index.js)	15.71KB	3.79KB
plugin-calendar (index.js)	45.98KB	12.65KB
plugin-charts (index.js)	45.46KB	12.78KB
plugin-chatbot (index.js)	159.77KB	38.54KB
plugin-dashboard (index.js)	107.36KB	26.65KB
plugin-designer (index.js)	213.42KB	42.94KB
plugin-detail (index.js)	198.30KB	47.91KB
plugin-editor (index.js)	2.38KB	1.06KB
plugin-form (index.js)	93.23KB	22.71KB
plugin-gantt (index.js)	136.68KB	33.88KB
plugin-grid (index.js)	121.64KB	32.95KB
plugin-kanban (index.js)	48.82KB	13.13KB
plugin-list (index.js)	94.53KB	22.32KB
plugin-map (index.js)	16.02KB	4.98KB
plugin-markdown (index.js)	13.58KB	4.64KB
plugin-report (index.js)	37.83KB	9.97KB
plugin-timeline (index.js)	25.37KB	7.20KB
plugin-tree (index.js)	8.21KB	2.76KB
plugin-view (index.js)	84.45KB	20.36KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.55KB	0.67KB
providers (UploadProvider.js)	11.71KB	3.53KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	18.23KB	5.97KB
react (index.js)	0.76KB	0.42KB
tenant (TenantContext.js)	0.31KB	0.25KB
tenant (TenantGuard.js)	1.04KB	0.43KB
tenant (TenantProvider.js)	2.76KB	0.98KB
tenant (TenantScopedQuery.js)	0.77KB	0.44KB
tenant (index.js)	0.75KB	0.38KB
tenant (resolver.js)	2.64KB	0.76KB
tenant (useTenant.js)	0.50KB	0.32KB
tenant (useTenantBranding.js)	0.62KB	0.39KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	0.77KB	0.41KB
types (disclosure.js)	0.20KB	0.18KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (index.js)	1.54KB	0.68KB
types (layout.js)	0.20KB	0.18KB
types (mobile.js)	0.20KB	0.18KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.26KB	1.96KB
types (tenant.js)	0.20KB	0.18KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	0.75KB	0.46KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped