@rebasepro/admin 0.0.1-canary.eae7889 → 0.0.1-canary.eb08332

package/src/components/{EntityCollectionView → CollectionViewBinding}/useBoardDataController.tsx

@@ -1,10 +1,30 @@
-import type { EntityCollection } from "@rebasepro/types";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { CollectionConfig } from "@rebasepro/types";
 import { Entity, FilterValues } from "@rebasepro/types";
-import { useData, useRebaseContext } from "@rebasepro/core";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useData, useRebaseContext } from "@rebasepro/app";
 
 const DEFAULT_PAGE_SIZE = 20;
 
+/**
+ * Shallow equality for entity value records.
+ * Handles primitives and reference equality for nested values.
+ * Avoids JSON.stringify allocation on every comparison.
+ */
+function shallowEqualValues(
+    a: Record<string, unknown> | undefined,
+    b: Record<string, unknown> | undefined
+): boolean {
+    if (a === b) return true;
+    if (!a || !b) return false;
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    for (const key of keysA) {
+        if (a[key] !== b[key]) return false;
+    }
+    return true;
+}
+
 /**
  * Data state for a single board column
  */
@@ -47,7 +67,7 @@ export interface UseBoardDataControllerProps<M extends Record<string, unknown> =
     /** Full path to the collection */
     fullPath: string;
     /** The entity collection configuration */
-    collection: EntityCollection<M>;
+    collection: CollectionConfig<M>;
     /** Property key used for column assignment */
     columnProperty: string;
     /** Array of column values (enum values from columnProperty) */
@@ -159,6 +179,34 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
         };
     }, []);
 
+    /**
+     * Check if a column value is excluded by the active filter on the columnProperty.
+     * E.g. if the user sets "Status IN (Open, In Progress)", this returns true
+     * for "Waiting on Customer" since that column should show as empty.
+     */
+    const isColumnExcludedByFilter = useCallback((column: string, filterValues?: FilterValues<string>, colProperty?: string): boolean => {
+        if (!filterValues || !colProperty) return false;
+        const filterForColumn = filterValues[colProperty as keyof typeof filterValues];
+        if (!filterForColumn || !Array.isArray(filterForColumn)) return false;
+
+        const [op, val] = filterForColumn as [string, unknown];
+
+        if (op === "==" && typeof val === "string") {
+            return column !== val;
+        }
+        if (op === "!=" && typeof val === "string") {
+            return column === val;
+        }
+        if (op === "in" && Array.isArray(val)) {
+            return !val.map(String).includes(column);
+        }
+        if (op === "not-in" && Array.isArray(val)) {
+            return val.map(String).includes(column);
+        }
+
+        return false;
+    }, []);
+
     // Helper function to subscribe to a single column - uses refs to avoid dependency issues
     const subscribeToColumn = useCallback((column: string, itemCount: number) => {
         // Skip if we're in the middle of cleanup
@@ -173,27 +221,30 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
         const currentSearchString = searchStringRef.current;
         const currentResolvedPath = resolvedPathRef.current;
 
-        // Build where map for this column
-        const whereMap: Record<string, string> = {};
-        if (currentFilterValues) {
-            Object.entries(currentFilterValues).forEach(([key, value]) => {
-                if (value && Array.isArray(value)) {
-                    const [op, val] = value;
-                    const postgrestOp = op === "==" ? "eq" : op === "!=" ? "neq" : op === ">" ? "gt" : op === ">=" ? "gte" : op === "<" ? "lt" : op === "<=" ? "lte" : op === "in" ? "in" : op === "not-in" ? "nin" : op === "array-contains" ? "cs" : op === "array-contains-any" ? "csa" : "eq";
-
-                    let stringVal: string;
-                    if (Array.isArray(val)) {
-                        stringVal = `(${val.join(",")})`;
-                    } else {
-                        stringVal = String(val);
-                    }
-                    whereMap[key] = `${postgrestOp}.${stringVal}`;
+        // If the column is excluded by the active filter on the column property,
+        // set it as empty immediately without querying.
+        const excluded = isColumnExcludedByFilter(column, currentFilterValues, currentColumnProperty);
+        if (excluded) {
+            setColumnData(prev => ({
+                ...prev,
+                [column]: {
+                    entities: [],
+                    loading: false,
+                    hasMore: false,
+                    error: undefined,
+                    totalCount: 0
                 }
-            });
+            }));
+            return;
         }
-        whereMap[currentColumnProperty] = `eq.${column}`;
 
-        const orderByParam = currentOrderProperty ? `${currentOrderProperty}:asc` : undefined;
+        // Build filter map for this column — pass FilterValues directly
+        const whereFilter: FilterValues<string> = {
+            ...(currentFilterValues ?? {}),
+            [currentColumnProperty]: ["==", column]
+        };
+
+        const orderByParam: [string, "asc" | "desc"] | undefined = currentOrderProperty ? [currentOrderProperty, "asc"] : undefined;
 
         // Mark column as loading
         setColumnData(prev => ({
@@ -211,7 +262,7 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
             if (isCleaningUpRef.current) return;
 
             const pendingMap = pendingItemsRef.current;
-            
+
             // Apply pending updates to incoming entities
             const mergedEntities = entities.map(e => {
                 const pending = pendingMap[String(e.id)];
@@ -219,7 +270,7 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                     // Check if DB entity has caught up to the expected column and order
                     const expectedCol = pending.expectedValues[currentColumnProperty];
                     const expectedOrder = currentOrderProperty ? pending.expectedValues[currentOrderProperty] : undefined;
-                    
+
                     let caughtUp = true;
                     if (e.values?.[currentColumnProperty] !== expectedCol) {
                         caughtUp = false;
@@ -227,15 +278,17 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                     if (currentOrderProperty && e.values?.[currentOrderProperty] !== expectedOrder) {
                         caughtUp = false;
                     }
-                    
+
                     if (caughtUp) {
                         // DB has caught up, clear pending state
                         delete pendingMap[String(e.id)];
                         return e; // Use the real DB entity
                     }
-                    
+
                     // DB hasn't caught up, overlay expected values
-                    return { ...e, values: { ...e.values, ...pending.expectedValues } };
+                    return { ...e,
+values: { ...e.values,
+...pending.expectedValues } };
                 }
                 return e;
             });
@@ -261,30 +314,36 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                 processed = [...processed].sort((a, b) => {
                     const valA = a.values?.[currentOrderProperty] as string | undefined | null;
                     const valB = b.values?.[currentOrderProperty] as string | undefined | null;
-                    
+
                     const isAEmpty = valA === undefined || valA === null || valA === "";
                     const isBEmpty = valB === undefined || valB === null || valB === "";
-                    
+
                     if (isAEmpty && isBEmpty) return 0;
                     if (isAEmpty) return 1;
                     if (isBEmpty) return -1;
-                    
+
                     return valA < valB ? -1 : valA > valB ? 1 : 0;
                 });
             }
 
-            // Apply afterRead callbacks if any
+            // Apply afterRead callbacks if any.
+            // afterRead operates on flat rows; unwrap the Entity view-model
+            // before invoking and re-wrap the processed row after.
             if (currentCollection.callbacks?.afterRead) {
                 try {
                     processed = await Promise.all(
-                        processed.map(entity =>
-                            currentCollection.callbacks!.afterRead!({
+                        processed.map(async (entity) => {
+                            const processedRow = await currentCollection.callbacks!.afterRead!({
                                 collection: currentCollection,
                                 path: currentResolvedPath,
-                                entity,
+                                row: { id: entity.id, ...entity.values },
                                 context: currentContext
-                            })
-                        )
+                            });
+                            return {
+                                ...entity,
+                                values: processedRow as M
+                            };
+                        })
                     );
                 } catch (e) {
                     console.error("Error in afterRead callback:", e);
@@ -293,8 +352,6 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
 
             const newHasMore = entities.length >= itemCount;
 
-            console.log(`[useBoardDataController] Listener update for col ${column}. Length: ${processed.length}. Entities:`, processed.map(e => e.id));
-
             // Compare with current state — skip update if identical to avoid UI flash
             setColumnData(prev => {
                 const existing = prev[column];
@@ -308,9 +365,9 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                             identical = false;
                             break;
                         }
-                        // Deep-compare values by JSON serialization
-                        // This covers order key, column assignment, and all other fields
-                        if (JSON.stringify(a.values) !== JSON.stringify(b.values)) {
+                        // Shallow-compare values to avoid JSON.stringify allocations
+                        // entity.values are flat records from the DB, so shallow suffices
+                        if (!shallowEqualValues(a.values, b.values)) {
                             identical = false;
                             break;
                         }
@@ -355,14 +412,14 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
         const accessor = currentDataClient.collection(currentResolvedPath);
         if (accessor.listen) {
             const unsubscribe = accessor.listen({
-                where: whereMap,
+                where: whereFilter,
                 limit: itemCount,
                 orderBy: orderByParam
             }, res => onUpdate(res.data as Entity<M>[]), onError);
             unsubscribersRef.current[column] = unsubscribe;
         } else {
             accessor.find({
-                where: whereMap,
+                where: whereFilter,
                 limit: itemCount,
                 orderBy: orderByParam
             })
@@ -404,31 +461,23 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                 const itemCount = currentColumnItemCounts[column] ?? pageSize;
                 subscribeToColumn(column, itemCount);
 
+                // Skip count query for columns excluded by the filter — subscribeToColumn
+                // already set them to totalCount: 0.
+                if (isColumnExcludedByFilter(column, currentFilterValues, currentColumnProperty)) {
+                    return;
+                }
+
                 // Count query for column (for display in column header)
                 const accessor = currentDataClient.collection(currentResolvedPath);
                 if (accessor.count) {
 
-                    const whereMap: Record<string, string> = {};
-                    if (currentFilterValues) {
-                        Object.entries(currentFilterValues).forEach(([key, value]) => {
-                            if (value && Array.isArray(value)) {
-                                const [op, val] = value;
-                                const postgrestOp = op === "==" ? "eq" : op === "!=" ? "neq" : op === ">" ? "gt" : op === ">=" ? "gte" : op === "<" ? "lt" : op === "<=" ? "lte" : op === "in" ? "in" : op === "not-in" ? "nin" : op === "array-contains" ? "cs" : op === "array-contains-any" ? "csa" : "eq";
-
-                                let stringVal: string;
-                                if (Array.isArray(val)) {
-                                    stringVal = `(${val.join(",")})`;
-                                } else {
-                                    stringVal = String(val);
-                                }
-                                whereMap[key] = `${postgrestOp}.${stringVal}`;
-                            }
-                        });
-                    }
-                    whereMap[currentColumnProperty] = `eq.${column}`;
+                    const whereFilter: FilterValues<string> = {
+                        ...(currentFilterValues ?? {}),
+                        [currentColumnProperty]: ["==", column]
+                    };
 
                     accessor.count({
-                        where: whereMap
+                        where: whereFilter
                     }).then(count => {
                         if (isCleaningUpRef.current) return;
                         setColumnData(prev => ({
@@ -549,7 +598,7 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                     ...itemToMove.values,
                     ...(newValues || {})
                 };
-                
+
                 const updatedEntity = {
                     ...itemToMove,
                     values: newValuesMerged
@@ -562,7 +611,7 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                 };
 
                 const targetEntities = sourceColumn === targetColumn ? sourceEntities : [...(updated[targetColumn]?.entities || [])];
-                
+
                 if (newIndex !== undefined && newIndex >= 0 && newIndex <= targetEntities.length) {
                     targetEntities.splice(newIndex, 0, updatedEntity);
                 } else {
@@ -572,15 +621,15 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                         targetEntities.sort((a, b) => {
                             const valA = a.values?.[orderProp] as string | undefined | null;
                             const valB = b.values?.[orderProp] as string | undefined | null;
-                            
+
                             // Handle nulls/empty strings to match Postgres NULLS LAST (ASC) behavior
                             const isAEmpty = valA === undefined || valA === null || valA === "";
                             const isBEmpty = valB === undefined || valB === null || valB === "";
-                            
+
                             if (isAEmpty && isBEmpty) return 0;
                             if (isAEmpty) return 1; // A is null, B is not -> A goes after B
                             if (isBEmpty) return -1; // B is null, A is not -> A goes before B
-                            
+
                             return valA < valB ? -1 : valA > valB ? 1 : 0;
                         });
                     }
@@ -589,8 +638,8 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                 updated[sourceColumn] = {
                     ...updated[sourceColumn],
                     entities: sourceColumn === targetColumn ? targetEntities : sourceEntities,
-                    totalCount: sourceColumn === targetColumn 
-                        ? updated[sourceColumn].totalCount 
+                    totalCount: sourceColumn === targetColumn
+                        ? updated[sourceColumn].totalCount
                         : Math.max(0, (updated[sourceColumn].totalCount ?? 0) - 1)
                 };
 
@@ -602,7 +651,6 @@ export function useBoardDataController<M extends Record<string, unknown> = any,
                     };
                 }
 
-                console.log(`[useBoardDataController] moveItemOptimistically: ${itemId} from ${sourceColumn} (${updated[sourceColumn].entities.length}) to ${targetColumn} (${updated[targetColumn].entities.length})`);
             } else if (sourceColumn !== targetColumn) {
                 // If item not found locally but counts need update
                 if (updated[sourceColumn]?.totalCount !== undefined) {

package/src/components/{EntityCollectionView/useEntityPreviewSlots.ts → CollectionViewBinding/usePreviewSlots.ts}

@@ -1,7 +1,8 @@
 import { useMemo } from "react";
-import type { EntityCollection, Property, RelationProperty } from "@rebasepro/types";
+import type { CollectionConfig, Property, RelationProperty } from "@rebasepro/types";
 import type { Entity, PropertyConfig, EntityRelation } from "@rebasepro/types";
 import { getEntityImagePreviewPropertyKey } from "@rebasepro/common";
+import { getEntityFromCache } from "@rebasepro/app";
 import { getEntityTitlePropertyKey, getEntityPreviewKeys } from "../../util/previews";
 import { getValueInPath } from "@rebasepro/utils";
 import type { AuthController } from "@rebasepro/types";
@@ -12,7 +13,7 @@ import { ChipColorScheme, CHIP_COLORS } from "@rebasepro/ui";
 
 /**
  * A resolved "slot" containing the property definition, key, and the
- * concrete value extracted from an entity.
+ * concrete value extracted from a entity.
  */
 export interface PreviewSlot {
     property: Property;
@@ -101,7 +102,7 @@ export interface CollectionSlotKeys {
  * Pure function — call inside `useMemo`.
  */
 export function resolveCollectionSlotKeys(
-    collection: EntityCollection<Record<string, unknown>>,
+    collection: CollectionConfig<Record<string, unknown>>,
     authController: AuthController,
     propertyConfigs: Record<string, PropertyConfig>
 ): CollectionSlotKeys {
@@ -110,11 +111,39 @@ export function resolveCollectionSlotKeys(
 
     // Status: first string-enum that isn't the title
     let statusKey: string | undefined;
-    for (const [key, prop] of Object.entries(collection.properties)) {
-        const p = prop as Property;
-        if (p.type === "string" && "enum" in p && p.enum && key !== titleKey) {
-            statusKey = key;
-            break;
+
+    // 1. Explicitly defined in previewProperties
+    if (!statusKey && collection.previewProperties) {
+        for (const key of collection.previewProperties) {
+            const p = collection.properties[key] as Property | undefined;
+            if (p?.type === "string" && "enum" in p && p.enum && key !== titleKey) {
+                statusKey = key;
+                break;
+            }
+        }
+    }
+
+    // 2. Explicitly defined in propertiesOrder
+    if (!statusKey && collection.propertiesOrder) {
+        for (const key of collection.propertiesOrder) {
+            if (typeof key === "string" && !key.startsWith("subcollection:")) {
+                const p = collection.properties[key] as Property | undefined;
+                if (p?.type === "string" && "enum" in p && p.enum && key !== titleKey) {
+                    statusKey = key;
+                    break;
+                }
+            }
+        }
+    }
+
+    // 3. Default automatic inference
+    if (!statusKey) {
+        for (const [key, prop] of Object.entries(collection.properties)) {
+            const p = prop as Property;
+            if (p.type === "string" && "enum" in p && p.enum && key !== titleKey) {
+                statusKey = key;
+                break;
+            }
         }
     }
 
@@ -137,31 +166,38 @@ export function resolveCollectionSlotKeys(
         }
     }
 
-    // Relations: collect ALL relation property keys.
-    // We iterate properties (not a hardcoded key list) and check the
-    // resolved relation metadata for type === "relation".
+    // Relations: collect relation property keys for chip rendering.
+    // When propertiesOrder is explicitly set, skip this — relations will
+    // be shown in the developer-defined order, not as separate chips.
+    const hasExplicitOrder = !!(collection.propertiesOrder as string[] | undefined);
     const relationKeys: string[] = [];
-    for (const [key, prop] of Object.entries(collection.properties)) {
-        const p = prop as Property;
-        if (p.type === "relation") {
-            relationKeys.push(key);
+    if (!hasExplicitOrder) {
+        for (const [key, prop] of Object.entries(collection.properties)) {
+            const p = prop as Property;
+            if (p.type === "relation") {
+                relationKeys.push(key);
+            }
         }
     }
 
-    // Subtitle: first preview key that isn't title/image/status/date/relation/id.
+    // Subtitle: first preview key that isn't title/image/status/date/id.
+    // When propertiesOrder is not set, also exclude relation keys (they render as chips).
     // Prefer string fields (especially multiline/description-like) over numbers.
     const excludeKeys = new Set([titleKey, imageKey, statusKey, dateKey, ...relationKeys]);
     const previewKeys = getEntityPreviewKeys(authController, collection, propertyConfigs, undefined, 10)
         .filter(k => !excludeKeys.has(k) && k !== "id");
 
-    // Sort: strings first (prefer multiline → good description candidate), then others
-    const sortedPreviewKeys = [...previewKeys].sort((a, b) => {
-        const propA = collection.properties[a] as Property | undefined;
-        const propB = collection.properties[b] as Property | undefined;
-        const scoreA = propA?.type === "string" ? (propA.multiline ? 2 : 1) : 0;
-        const scoreB = propB?.type === "string" ? (propB.multiline ? 2 : 1) : 0;
-        return scoreB - scoreA;
-    });
+    // When propertiesOrder is set, respect the developer-defined order (no re-sorting).
+    // When not set, sort: strings first (prefer multiline → good description candidate).
+    const sortedPreviewKeys = hasExplicitOrder
+        ? previewKeys
+        : [...previewKeys].sort((a, b) => {
+            const propA = collection.properties[a] as Property | undefined;
+            const propB = collection.properties[b] as Property | undefined;
+            const scoreA = propA?.type === "string" ? (propA.ui?.multiline ? 2 : 1) : 0;
+            const scoreB = propB?.type === "string" ? (propB.ui?.multiline ? 2 : 1) : 0;
+            return scoreB - scoreA;
+        });
     const subtitleKey = sortedPreviewKeys.length > 0 ? sortedPreviewKeys[0] : undefined;
 
     return { titleKey,
@@ -180,7 +216,7 @@ dateKey };
  * and value is the first element (for arrays) or the raw value.
  */
 function resolveImageSlot(
-    collection: EntityCollection<Record<string, unknown>>,
+    collection: CollectionConfig<Record<string, unknown>>,
     imageKey: string,
     entity: Entity<Record<string, unknown>>
 ): PreviewSlot | undefined {
@@ -241,7 +277,7 @@ function formatDateValue(value: unknown): string {
  * `resolveEntitySlots` for each entity row.
  */
 export function useCollectionSlotKeys(
-    collection: EntityCollection<Record<string, unknown>>,
+    collection: CollectionConfig<Record<string, unknown>>,
     authController: AuthController,
     propertyConfigs: Record<string, PropertyConfig>
 ): CollectionSlotKeys {
@@ -260,7 +296,7 @@ export function useCollectionSlotKeys(
  */
 export function resolveEntitySlots(
     entity: Entity<Record<string, unknown>>,
-    collection: EntityCollection<Record<string, unknown>>,
+    collection: CollectionConfig<Record<string, unknown>>,
     slotKeys: CollectionSlotKeys
 ): EntityPreviewSlots {
     const { titleKey, imageKey, subtitleKey, relationKeys, statusKey, dateKey } = slotKeys;
@@ -304,7 +340,7 @@ value: val };
         const items: RelationChipItem[] = [];
         let totalCount = 0;
 
-        const isMany = prop.relation?.cardinality === "many";
+        const isMany = prop.cardinality === "many" || prop.relation?.cardinality === "many";
 
         if (isMany && Array.isArray(val)) {
             // cardinality:"many" → array of EntityRelation
@@ -322,9 +358,12 @@ id });
             }
         } else if (!isMany && val && typeof val === "object") {
             // cardinality:"one" → single EntityRelation
-            const isRelation = "__type" in val && (val as Record<string, unknown>).__type === "relation";
+            const obj = val as Record<string, unknown>;
+            const isRelation = ("__type" in obj && obj.__type === "relation")
+                || (typeof obj.isEntityRelation === "function"
+                    && (obj.isEntityRelation as () => boolean)());
             if (isRelation) {
-                const relation = val as unknown as EntityRelation;
+                const relation = obj as unknown as EntityRelation;
                 const displayName = resolveRelationDisplayName(relation, prop);
                 totalCount = 1;
                 if (displayName) {
@@ -400,43 +439,92 @@ function resolveRelationDisplayName(
 ): string | undefined {
     // Support both EntityRelation instances and plain objects
     const data = "data" in relation ? (relation as EntityRelation).data : undefined;
-    if (!data || !data.values) {
-        // No eagerly-loaded data — fall back to ID
-        const id = "id" in relation ? relation.id : undefined;
-        return id !== undefined ? String(id) : undefined;
-    }
-
-    const values = data.values as Record<string, unknown>;
 
-    // Try using the target collection's title property for accuracy
+    // Resolve target collection from either `prop.relation.target()` or `prop.target()` (inline API)
+    let targetCollection: CollectionConfig | undefined;
     try {
-        const targetCollection = prop.relation?.target?.();
+        const resolved = prop.relation?.target?.() ?? (typeof prop.target === "function" ? prop.target() : undefined);
+        if (resolved && typeof resolved === "object") {
+            targetCollection = resolved as CollectionConfig;
+        }
+    } catch {
+        // Target collection may not be resolvable
+    }
+
+    // Helper: extract display name from entity values using the target collection
+    const extractDisplayName = (values: Record<string, unknown>): string | undefined => {
         if (targetCollection) {
             const targetTitleKey = targetCollection.titleProperty as string | undefined;
             if (targetTitleKey && values[targetTitleKey] !== undefined) {
                 return String(values[targetTitleKey]);
             }
-            // Fallback: find first non-id string property in target
+
+            // Helper to check if a property is hidden/internal
+            const isHiddenProp = (p: Property): boolean => {
+                if (p.ui?.hideFromCollection) return true;
+                if (typeof p.ui?.disabled === "object" && p.ui.disabled.hidden) return true;
+                return false;
+            };
+
+            // Helper to check if a property is a visible, non-id string
+            const isDisplayCandidate = (p: Property): boolean => {
+                return p.type === "string" && !p.ui?.multiline && !p.ui?.markdown && !p.storage
+                    && !("isId" in p && p.isId) && !isHiddenProp(p);
+            };
+
+            // Prioritize common title-like fields: name, title, label, displayName
+            const priorityKeys = ["name", "title", "label", "displayName"];
+            for (const pk of priorityKeys) {
+                const p = targetCollection.properties[pk] as Property | undefined;
+                if (p && isDisplayCandidate(p) && values[pk] !== undefined && values[pk] !== null) {
+                    return String(values[pk]);
+                }
+            }
+
+            // Fallback: find first visible, non-id string property in target
             for (const [k, p] of Object.entries(targetCollection.properties)) {
                 const tp = p as Property;
-                if (tp.type === "string" && !tp.multiline && !tp.markdown && !tp.storage && !("isId" in tp && tp.isId)) {
+                if (isDisplayCandidate(tp)) {
                     if (values[k] !== undefined && values[k] !== null) {
                         return String(values[k]);
                     }
                 }
             }
         }
-    } catch {
-        // Target collection may not be resolvable — fall through
+        // Generic fallback: walk entity values for any short string.
+        for (const [, v] of Object.entries(values)) {
+            if (typeof v === "string" && v.length > 0 && v.length < 200) {
+                return v;
+            }
+        }
+        return undefined;
+    };
+
+    // 1. Try eagerly-loaded data on the relation object
+    if (data && data.values) {
+        const result = extractDisplayName(data.values as Record<string, unknown>);
+        if (result) return result;
     }
 
-    // Generic fallback: walk entity values for any short string.
-    for (const [, v] of Object.entries(values)) {
-        if (typeof v === "string" && v.length > 0 && v.length < 200) {
-            return v;
+    const id = "id" in relation ? relation.id : undefined;
+
+    // 2. Try the entity cache (sessionStorage) as a fallback
+    if (id !== undefined && targetCollection) {
+        try {
+            const slug = targetCollection.slug ?? ("table" in targetCollection ? targetCollection.table : undefined);
+            if (slug) {
+                const cacheKey = `${slug}/${id}`;
+                const cached = getEntityFromCache(cacheKey) as { values?: Record<string, unknown> } | undefined;
+                if (cached?.values) {
+                    const result = extractDisplayName(cached.values);
+                    if (result) return result;
+                }
+            }
+        } catch {
+            // Cache lookup failed — fall through
         }
     }
 
-    const id = "id" in relation ? relation.id : undefined;
+    // 3. Final fallback: show the ID
     return id !== undefined ? String(id) : undefined;
 }