@object-ui/fields 4.0.7 → 4.0.9

package/src/index.tsx

@@ -9,8 +9,122 @@
 import React from 'react';
 import type { FieldMetadata, SelectOptionMetadata } from '@object-ui/types';
 import { ComponentRegistry } from '@object-ui/core';
-import { Badge, Avatar, AvatarFallback, Button, Checkbox, EmptyValue } from '@object-ui/components';
+import { Badge, Avatar, AvatarFallback, Button, Checkbox, EmptyValue, cn } from '@object-ui/components';
 import { Check, X, Copy, Phone as PhoneIcon } from 'lucide-react';
+import { useObjectTranslation } from '@object-ui/react';
+import { SchemaRendererContext as _SchemaRendererContext } from '@object-ui/react';
+
+// Module-level cache so multiple renderers fetching the same lookup ID
+// only trigger one network call. Keyed by `${objectName}:${id}`.
+type LookupCacheEntry =
+  | { state: 'pending'; promise: Promise<void> }
+  | { state: 'ok'; name: string | undefined }
+  | { state: 'err' };
+const lookupNameCache: Map<string, LookupCacheEntry> = new Map();
+
+/**
+ * Pick the most reasonable display name from an arbitrary record object.
+ * Tries common name-like keys in priority order, then falls back to undefined.
+ */
+function pickRecordDisplayName(record: Record<string, unknown> | null | undefined): string | undefined {
+  if (!record || typeof record !== 'object') return undefined;
+  const candidates = ['name', 'full_name', 'display_name', 'label', 'title', 'subject', 'username', 'email'];
+  for (const k of candidates) {
+    const v = record[k];
+    if (typeof v === 'string' && v.trim()) return v.trim();
+    if (typeof v === 'number') return String(v);
+  }
+  return undefined;
+}
+
+/**
+ * Heuristic: detect strings that look like opaque foreign-key IDs (e.g. nanoid
+ * or BSON ObjectId). Used so we don't display random gibberish to users when
+ * a lookup wasn't expanded.
+ */
+export function isLikelyOpaqueId(v: unknown): boolean {
+  if (typeof v !== 'string') return false;
+  // 12-32 chars, only [A-Za-z0-9_-], no whitespace.
+  if (!/^[A-Za-z0-9_-]{12,32}$/.test(v)) return false;
+  // Must have BOTH upper- and lower-case letters (real words rarely do at this length).
+  // Also accept tokens that contain `_` or `-` separators alongside any case mix.
+  const hasUpper = /[A-Z]/.test(v);
+  const hasLower = /[a-z]/.test(v);
+  const hasDigitOrSep = /[0-9_-]/.test(v);
+  return (hasUpper && hasLower) || (hasUpper && hasDigitOrSep) || (hasLower && hasDigitOrSep);
+}
+
+/**
+ * Fetch-on-demand resolver for foreign-key IDs that weren't expanded by the
+ * server. Reads `dataSource` from SchemaRendererContext; safely no-ops if
+ * the context isn't installed. Returns the resolved display name or
+ * `undefined` while pending or unresolvable.
+ */
+function useLookupName(referenceTo: string | undefined, value: unknown): string | undefined {
+  const ctx = React.useContext(_SchemaRendererContext);
+  const dataSource = ctx?.dataSource;
+  const [, force] = React.useState(0);
+
+  const isResolvable =
+    !!referenceTo &&
+    !!dataSource &&
+    typeof dataSource.find === 'function' &&
+    (typeof value === 'string' || typeof value === 'number') &&
+    value !== '';
+  const cacheKey = isResolvable ? `${referenceTo}:${String(value)}` : '';
+
+  React.useEffect(() => {
+    if (!isResolvable) return;
+    const existing = lookupNameCache.get(cacheKey);
+    if (existing && existing.state !== 'pending' && (existing as any).promise == null) return;
+    if (existing?.state === 'pending') return;
+
+    const promise: Promise<void> = (async () => {
+      try {
+        let record: Record<string, unknown> | undefined;
+        if (typeof (dataSource as any).findOne === 'function') {
+          record = await (dataSource as any).findOne(referenceTo, value);
+        } else {
+          const result = await (dataSource as any).find(referenceTo, {
+            $filter: { id: value },
+            options: { $top: 1 },
+          });
+          const records: any[] = Array.isArray(result)
+            ? result
+            : (result?.value || result?.data || []);
+          record = records[0];
+        }
+        const name = pickRecordDisplayName(record);
+        lookupNameCache.set(cacheKey, { state: 'ok', name });
+      } catch {
+        lookupNameCache.set(cacheKey, { state: 'err' });
+      }
+      force((n) => n + 1);
+    })();
+
+    lookupNameCache.set(cacheKey, { state: 'pending', promise });
+  }, [cacheKey, isResolvable, referenceTo, value, dataSource]);
+
+  if (!isResolvable) return undefined;
+  const entry = lookupNameCache.get(cacheKey);
+  return entry?.state === 'ok' ? entry.name : undefined;
+}
+
+/**
+ * Safe label resolver for cell-level UI strings. Falls back to the English
+ * default when no I18nProvider is available or when the key is missing.
+ */
+function useFieldLabel() {
+  try {
+    const { t } = useObjectTranslation();
+    return (key: string, fallback: string) => {
+      const v = t(key);
+      return !v || v === key ? fallback : v;
+    };
+  } catch {
+    return (_k: string, fallback: string) => fallback;
+  }
+}
 
 import { TextField } from './widgets/TextField';
 import { NumberField } from './widgets/NumberField';
@@ -127,6 +241,22 @@ export function formatCompactCurrency(value: number, currency: string = 'USD'):
   }
 }
 
+/**
+ * Format a plain number with thousands separators, no currency symbol.
+ * Used as a safe fallback when a currency-typed field has no `currency`
+ * configured — we'd rather render `1,234.50` than silently assume USD.
+ */
+export function formatNumber(value: number, decimals: number = 2): string {
+  try {
+    return new Intl.NumberFormat('en-US', {
+      minimumFractionDigits: decimals,
+      maximumFractionDigits: decimals,
+    }).format(value);
+  } catch {
+    return value.toFixed(decimals);
+  }
+}
+
 /**
  * Format percent value
  * Handles both decimal (0.8 = 80%) and whole number (80 = 80%) inputs.
@@ -153,10 +283,10 @@ export function humanizeLabel(value: string): string {
 /**
  * Format date as relative time (e.g., "2 days ago", "Today", "Overdue 3d")
  */
-export function formatRelativeDate(value: string | Date): string {
-  if (!value) return '—';
-  const date = typeof value === 'string' ? new Date(value) : value;
-  if (isNaN(date.getTime())) return '—';
+export function formatRelativeDate(value: string | Date | number): string {
+  if (value === null || value === undefined || value === '') return '—';
+  const date = value instanceof Date ? value : new Date(value as any);
+  if (!(date instanceof Date) || isNaN(date.getTime())) return '—';
 
   const now = new Date();
   const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate());
@@ -179,10 +309,10 @@ export function formatRelativeDate(value: string | Date): string {
 /**
  * Format date value
  */
-export function formatDate(value: string | Date, style?: string): string {
-  if (!value) return '—';
-  const date = typeof value === 'string' ? new Date(value) : value;
-  if (isNaN(date.getTime())) return '—';
+export function formatDate(value: string | Date | number, style?: string): string {
+  if (value === null || value === undefined || value === '') return '—';
+  const date = value instanceof Date ? value : new Date(value as any);
+  if (!(date instanceof Date) || isNaN(date.getTime())) return '—';
 
   if (style === 'short') {
     // Compact format for mobile: "Jan 15, '24"
@@ -207,10 +337,10 @@ export function formatDate(value: string | Date, style?: string): string {
 /**
  * Format datetime value
  */
-export function formatDateTime(value: string | Date): string {
-  if (!value) return '—';
-  const date = typeof value === 'string' ? new Date(value) : value;
-  if (isNaN(date.getTime())) return '—';
+export function formatDateTime(value: string | Date | number): string {
+  if (value === null || value === undefined || value === '') return '—';
+  const date = value instanceof Date ? value : new Date(value as any);
+  if (!(date instanceof Date) || isNaN(date.getTime())) return '—';
   
   return date.toLocaleDateString(undefined, {
     year: 'numeric',
@@ -255,9 +385,14 @@ export function CurrencyCellRenderer({ value, field }: CellRendererProps): React
   
   const safe = coerceToSafeValue(value);
   const currencyField = field as any;
-  const currency = currencyField.currency || 'USD';
+  // Honor both `currency` (legacy/grid configs) and `defaultCurrency`
+  // (the canonical key from `@objectstack/spec` Field.currency()).
+  const currency: string | undefined = currencyField.currency || currencyField.defaultCurrency;
   const num = Number(safe);
-  const formatted = !isNaN(num) ? formatCurrency(num, currency) : String(safe);
+  const decimals = currencyField.precision ?? currencyField.scale ?? currencyField.decimals ?? 2;
+  const formatted = !isNaN(num)
+    ? (currency ? formatCurrency(num, currency) : formatNumber(num, decimals))
+    : String(safe);
   
   return <span className="tabular-nums font-medium whitespace-nowrap">{formatted}</span>;
 }
@@ -290,7 +425,7 @@ export function PercentCellRenderer({ value, field }: CellRendererProps): React.
   return (
     <div className="flex items-center gap-2">
       <div
-        className="h-1.5 w-16 rounded-full bg-muted overflow-hidden shrink-0"
+        className="h-1.5 w-16 rounded-full bg-muted ring-1 ring-inset ring-border/60 overflow-hidden shrink-0"
         role="progressbar"
         aria-valuenow={clampedBar}
         aria-valuemin={0}
@@ -351,7 +486,7 @@ export function BooleanCellRenderer({ value, field }: CellRendererProps): React.
   }
 
   return (
-    <div className="flex items-center justify-center">
+    <div className="flex items-center justify-start">
       <Checkbox checked={!!value} disabled className="pointer-events-none" />
     </div>
   );
@@ -370,16 +505,16 @@ export function DateCellRenderer({ value, field }: CellRendererProps): React.Rea
   // Determine if date is overdue (in the past) — but only color it red when the
   // field is *semantically* a due/deadline. A plain "start_date" or "created_at"
   // in the past should not render in red.
-  const date = typeof safe === 'string' ? new Date(safe) : safe;
-  const isValidDate = date instanceof Date && !isNaN(date.getTime());
+  const date = safe != null ? new Date(safe as string | number) : null;
+  const isValidDate = date !== null && !isNaN(date.getTime());
   const startOfToday = new Date();
   startOfToday.setHours(0, 0, 0, 0);
   const fieldName = String(dateField?.name || dateField?.accessorKey || dateField?.key || '').toLowerCase();
   const dueLike =
     dateField?.dueLike === true ||
     /(^|_)(due|deadline|expires?|expiry|expiration|expected_close|target_close|sla|return_by|renewal|next_action)(_|$)/.test(fieldName);
-  const isOverdue = dueLike && isValidDate && date < startOfToday;
-  const isoString = isValidDate ? date.toISOString() : String(safe);
+  const isOverdue = dueLike && isValidDate && date! < startOfToday;
+  const isoString = isValidDate ? date!.toISOString() : String(safe);
 
   return (
     <span
@@ -397,8 +532,8 @@ export function DateCellRenderer({ value, field }: CellRendererProps): React.Rea
 export function DateTimeCellRenderer({ value }: CellRendererProps): React.ReactElement {
   if (!value) return <EmptyValue />;
   const safe = coerceToSafeValue(value);
-  const date = typeof safe === 'string' ? new Date(safe) : safe;
-  if (!(date instanceof Date) || isNaN(date.getTime())) return <EmptyValue />;
+  const date = safe != null ? new Date(safe as string | number) : null;
+  if (date === null || isNaN(date.getTime())) return <EmptyValue />;
 
   const datePart = date.toLocaleDateString(undefined, {
     month: 'numeric',
@@ -421,8 +556,9 @@ export function DateTimeCellRenderer({ value }: CellRendererProps): React.ReactE
 
 // Semantic color mapping (auto-detect from value text for priority & status fields)
 // Keys use underscore notation; lookup normalizes spaces/hyphens to underscores automatically.
+// Chinese keys are stored as-is and matched directly (no normalization side-effects).
 const SEMANTIC_COLOR_MAP: Record<string, string> = {
-  // Priority values
+  // Priority values (en)
   critical: 'red',
   urgent: 'red',
   high: 'orange',
@@ -430,7 +566,7 @@ const SEMANTIC_COLOR_MAP: Record<string, string> = {
   normal: 'blue',
   low: 'gray',
   none: 'gray',
-  // Status values
+  // Status values (en)
   paid: 'green',
   completed: 'green',
   done: 'green',
@@ -455,6 +591,52 @@ const SEMANTIC_COLOR_MAP: Record<string, string> = {
   overdue: 'red',
   delivered: 'purple',
   archived: 'indigo',
+  // CRM lifecycle values (en)
+  contacted: 'blue',
+  qualified: 'purple',
+  converted: 'green',
+  won: 'green',
+  lost: 'red',
+  // Priority values (zh)
+  紧急: 'red',
+  严重: 'red',
+  高: 'orange',
+  中: 'yellow',
+  普通: 'blue',
+  低: 'gray',
+  无: 'gray',
+  // Status values (zh)
+  新建: 'gray',
+  草稿: 'gray',
+  待处理: 'yellow',
+  待审核: 'yellow',
+  待联系: 'yellow',
+  挂起: 'yellow',
+  进行中: 'blue',
+  处理中: 'blue',
+  已联系: 'blue',
+  跟进中: 'blue',
+  已发货: 'blue',
+  打开: 'blue',
+  已确认: 'green',
+  已审核: 'green',
+  已通过: 'green',
+  已完成: 'green',
+  已支付: 'green',
+  已签收: 'green',
+  已转化: 'green',
+  成单: 'green',
+  赢得: 'green',
+  已签约: 'green',
+  已交付: 'purple',
+  已归档: 'indigo',
+  已关闭: 'gray',
+  已取消: 'red',
+  已拒绝: 'red',
+  失败: 'red',
+  逾期: 'red',
+  流失: 'red',
+  丢失: 'red',
 };
 
 // Color to Tailwind class mapping for custom Badge styling
@@ -475,6 +657,22 @@ const BADGE_COLOR_MAP: Record<string, string> = {
   pink: 'bg-pink-50 text-pink-700 border-pink-200 dark:bg-pink-950/40 dark:text-pink-300 dark:border-pink-900/60',
 };
 
+// Solid color → Tailwind background class for the small dot used by the
+// `appearance: 'dot'` rendering of select/status fields. Uses the -500 shade
+// for both light and dark modes so the dot remains a clear visual anchor
+// without becoming a heavy color block.
+const DOT_COLOR_MAP: Record<string, string> = {
+  gray: 'bg-gray-400 dark:bg-gray-500',
+  red: 'bg-red-500',
+  orange: 'bg-orange-500',
+  yellow: 'bg-yellow-500',
+  green: 'bg-green-500',
+  blue: 'bg-blue-500',
+  indigo: 'bg-indigo-500',
+  purple: 'bg-purple-500',
+  pink: 'bg-pink-500',
+};
+
 // Color palette used by the deterministic fallback when no schema/semantic
 // color matches. Excludes 'gray' to ensure visual contrast between values.
 const BADGE_FALLBACK_PALETTE: readonly string[] = [
@@ -494,7 +692,7 @@ function hashToColor(value: string): string {
   return BADGE_FALLBACK_PALETTE[idx];
 }
 
-function getBadgeColorClasses(color?: string, val?: unknown): string {
+export function getBadgeColorClasses(color?: string, val?: unknown): string {
   if (color && BADGE_COLOR_MAP[color]) return BADGE_COLOR_MAP[color];
   if (val == null || val === '') return 'bg-muted text-muted-foreground border-border';
   const key = String(val).toLowerCase().replace(/[\s-]/g, '_');
@@ -506,50 +704,121 @@ function getBadgeColorClasses(color?: string, val?: unknown): string {
 }
 
 /**
- * Select field cell renderer (with badges)
+ * Resolve a semantic color name (e.g. "red", "green") for a value, suitable
+ * for callers that need a raw color token rather than CSS classes (for
+ * example, the Gantt renderer paints bars via inline styles).
+ *
+ * Resolution order: explicit option color → semantic value mapping →
+ * deterministic hash fallback. Returns `undefined` only when no value is
+ * supplied so the caller can fall back to its own default.
+ */
+export function getSemanticColorName(color?: string, val?: unknown): string | undefined {
+  if (color && BADGE_COLOR_MAP[color]) return color;
+  if (val == null || val === '') return undefined;
+  const key = String(val).toLowerCase().replace(/[\s-]/g, '_');
+  const semantic = SEMANTIC_COLOR_MAP[key];
+  if (semantic) return semantic;
+  return hashToColor(key);
+}
+
+// Resolved hex values for the -500 shade of each palette color. Mirrors
+// `DOT_COLOR_MAP` and is consumed by callers that paint via inline styles
+// (e.g. Gantt task bars, where Tailwind classes can't be applied to dynamic
+// `style={}` values).
+const COLOR_NAME_HEX: Record<string, string> = {
+  gray: '#6b7280',
+  red: '#ef4444',
+  orange: '#f97316',
+  yellow: '#eab308',
+  green: '#22c55e',
+  blue: '#3b82f6',
+  indigo: '#6366f1',
+  purple: '#a855f7',
+  pink: '#ec4899',
+};
+
+/**
+ * Map a semantic color name to its Tailwind -500 hex value. Used by
+ * inline-style consumers (Gantt bars). Falls back to the supplied default
+ * (or the platform default blue) when the name is unrecognized.
+ */
+export function getSemanticHex(name?: string, fallback: string = '#3b82f6'): string {
+  if (!name) return fallback;
+  return COLOR_NAME_HEX[name] ?? fallback;
+}
+
+/**
+ * Select field cell renderer.
+ *
+ * Two visual styles, controlled by `field.appearance` (renderer-level option,
+ * not part of the `@objectstack/spec` field schema):
+ *   - `'badge'` (default for spec compatibility): soft-pill colored badge.
+ *   - `'dot'`: a small colored dot followed by the option label. Used by
+ *     dense list/grid contexts to keep the table visually quiet — repeated
+ *     filled badges across many rows create heavy visual noise.
+ *
+ * Metadata always wins: callers can pass `appearance: 'badge'` on the field
+ * descriptor to force the legacy badge in any context.
  */
 export function SelectCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
   const selectField = field as any;
   const options: SelectOptionMetadata[] = selectField.options || [];
-  
+  const appearance: 'badge' | 'dot' = selectField.appearance === 'dot' ? 'dot' : 'badge';
+
   if (value == null || value === '') return <EmptyValue />;
-  
+
+  // Match a stored value to a configured option, falling back to a
+  // case-insensitive comparison so seed data with mixed case
+  // (e.g. "Referral" stored, "referral" defined) still resolves to the
+  // localized option label.
+  const findOption = (val: any): SelectOptionMetadata | undefined => {
+    const exact = options.find(opt => opt.value === val);
+    if (exact) return exact;
+    const norm = String(val).toLowerCase();
+    return options.find(opt => String(opt.value).toLowerCase() === norm);
+  };
+
+  const renderOne = (val: any, key?: number): React.ReactElement => {
+    const option = findOption(val);
+    const label = option?.label || humanizeLabel(String(val));
+
+    if (appearance === 'dot') {
+      // Resolve a real CSS color for the dot. Prefer explicit option color,
+      // then semantic mapping for the value, then deterministic palette.
+      const colorName = option?.color
+        || SEMANTIC_COLOR_MAP[String(val).toLowerCase().replace(/[\s-]/g, '_')]
+        || hashToColor(String(val).toLowerCase().replace(/[\s-]/g, '_'));
+      const dotClass = DOT_COLOR_MAP[colorName] || DOT_COLOR_MAP.gray;
+      return (
+        <span key={key} className="inline-flex items-center gap-1.5 text-sm">
+          <span className={cn('h-1.5 w-1.5 rounded-full shrink-0', dotClass)} aria-hidden="true" />
+          <span className="truncate">{label}</span>
+        </span>
+      );
+    }
+
+    const colorClasses = getBadgeColorClasses(option?.color, val);
+    return (
+      <Badge
+        key={key}
+        variant="outline"
+        className={colorClasses}
+      >
+        {label}
+      </Badge>
+    );
+  };
+
   // Handle multiple values
   if (Array.isArray(value)) {
     return (
-      <div className="flex flex-wrap gap-1">
-        {value.map((val, idx) => {
-          const option = options.find(opt => opt.value === val);
-          const label = option?.label || humanizeLabel(String(val));
-          const colorClasses = getBadgeColorClasses(option?.color, val);
-          
-          return (
-            <Badge
-              key={idx}
-              variant="outline"
-              className={colorClasses}
-            >
-              {label}
-            </Badge>
-          );
-        })}
+      <div className={cn('flex flex-wrap', appearance === 'dot' ? 'gap-x-3 gap-y-1' : 'gap-1')}>
+        {value.map((val, idx) => renderOne(val, idx))}
       </div>
     );
   }
-  
-  // Handle single value
-  const option = options.find(opt => opt.value === value);
-  const label = option?.label || humanizeLabel(String(value));
-  const colorClasses = getBadgeColorClasses(option?.color, value);
-  
-  return (
-    <Badge
-      variant="outline"
-      className={colorClasses}
-    >
-      {label}
-    </Badge>
-  );
+
+  return renderOne(value);
 }
 
 /**
@@ -557,7 +826,8 @@ export function SelectCellRenderer({ value, field }: CellRendererProps): React.R
  */
 export function EmailCellRenderer({ value }: CellRendererProps): React.ReactElement {
   if (!value) return <EmptyValue />;
-  
+
+  const label = useFieldLabel();
   const safe = String(coerceToSafeValue(value) ?? '');
   const [copied, setCopied] = React.useState(false);
 
@@ -588,7 +858,7 @@ export function EmailCellRenderer({ value }: CellRendererProps): React.ReactElem
         type="button"
         className="opacity-0 group-hover/email:opacity-100 transition-opacity p-0.5 rounded hover:bg-muted"
         onClick={handleCopy}
-        aria-label="Copy email"
+        aria-label={label('detail.copyEmail', 'Copy email')}
       >
         {copied ? (
           <Check className="h-3 w-3 text-green-600" />
@@ -630,7 +900,8 @@ export function UrlCellRenderer({ value }: CellRendererProps): React.ReactElemen
  */
 export function PhoneCellRenderer({ value }: CellRendererProps): React.ReactElement {
   if (!value) return <EmptyValue />;
-  
+
+  const label = useFieldLabel();
   const safe = String(coerceToSafeValue(value) ?? '');
   const [copied, setCopied] = React.useState(false);
 
@@ -657,7 +928,7 @@ export function PhoneCellRenderer({ value }: CellRendererProps): React.ReactElem
         type="button"
         className="opacity-0 group-hover/phone:opacity-100 transition-opacity p-0.5 rounded hover:bg-muted"
         onClick={handleCopy}
-        aria-label="Copy phone number"
+        aria-label={label('detail.copyPhone', 'Copy phone number')}
       >
         {copied ? (
           <Check className="h-3 w-3 text-green-600" />
@@ -727,21 +998,62 @@ export function ImageCellRenderer({ value }: CellRendererProps): React.ReactElem
 }
 
 /**
- * Lookup/Master-Detail field cell renderer
+ * Lookup/Master-Detail field cell renderer.
+ *
+ * Display order:
+ * 1. Embedded record object (`{ id, name, ... }` from `$expand`) → use its name
+ * 2. Static `field.options[]` (e.g. when the lookup is a closed enum) → look up label
+ * 3. Fetch-on-demand: when the value is a primitive ID and `field.reference_to`
+ *    is known, resolve via dataSource and show the related record's display name.
+ *    Falls back to a muted placeholder while pending and on failure.
  */
 export function LookupCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
+  const referenceTo = (field as { reference_to?: string }).reference_to;
+
+  // Pick the FIRST primitive id we see (for arrays, only the first one is auto-resolved
+  // to keep the cell cheap; multi-value lookups should generally be expanded server-side).
+  const primaryPrimitiveId = (() => {
+    if (Array.isArray(value)) {
+      const firstPrimitive = value.find(
+        (v) => v != null && (typeof v === 'string' || typeof v === 'number') && v !== '',
+      );
+      return firstPrimitive;
+    }
+    if (
+      value != null &&
+      value !== '' &&
+      (typeof value === 'string' || typeof value === 'number') &&
+      typeof value !== 'object'
+    ) {
+      return value;
+    }
+    return undefined;
+  })();
+
+  // Always call the hook (rules of hooks). It safely no-ops when inputs are missing.
+  const resolvedName = useLookupName(referenceTo, primaryPrimitiveId);
+
   if (value == null || value === '') return <EmptyValue />;
 
   const options: Array<{ value: unknown; label: string }> =
     (field as { options?: Array<{ value: unknown; label: string }> }).options || [];
 
-  // Resolve a primitive ID to a label via options if available
-  const resolveLabel = (val: unknown): string => {
+  // Resolve a primitive ID to a label. Order:
+  //   options → server-resolved name (via useLookupName) → muted placeholder for opaque IDs → raw value
+  const resolveLabel = (val: unknown): { text: string; muted: boolean } => {
     if (options.length > 0) {
       const found = options.find((opt) => String(opt.value) === String(val));
-      if (found) return found.label;
+      if (found) return { text: found.label, muted: false };
+    }
+    if (val === primaryPrimitiveId && resolvedName) {
+      return { text: resolvedName, muted: false };
     }
-    return String(val);
+    if (isLikelyOpaqueId(val)) {
+      // Don't dump a random-looking ID at the user. Show a soft placeholder
+      // that conveys "this is a reference, name unavailable".
+      return { text: '—', muted: true };
+    }
+    return { text: String(val), muted: false };
   };
 
   if (Array.isArray(value)) {
@@ -749,15 +1061,23 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
       <div className="flex flex-wrap gap-1">
         {value.map((item, idx) => {
           let label: string;
+          let muted = false;
           if (item != null && typeof item === 'object') {
-            label = item.name || item.label || item.id || item._id || String(item);
+            label = pickRecordDisplayName(item as Record<string, unknown>) || String((item as any).id || (item as any)._id || '[Object]');
           } else {
-            label = resolveLabel(item);
+            const r = resolveLabel(item);
+            label = r.text;
+            muted = r.muted;
           }
           return (
             <span
               key={idx}
-              className="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-gray-50 text-gray-700 dark:bg-gray-800/50 dark:text-gray-200"
+              className={cn(
+                'inline-flex items-center px-2 py-0.5 rounded text-xs font-medium',
+                muted
+                  ? 'bg-muted/40 text-muted-foreground'
+                  : 'bg-gray-50 text-gray-700 dark:bg-gray-800/50 dark:text-gray-200',
+              )}
             >
               {label}
             </span>
@@ -766,14 +1086,17 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
       </div>
     );
   }
-  
+
   if (typeof value === 'object' && value !== null) {
-    const label = value.name || value.label || value.id || value._id || '[Object]';
+    const label =
+      pickRecordDisplayName(value as Record<string, unknown>) ||
+      String((value as any).id || (value as any)._id || '[Object]');
     return <span className="truncate">{label}</span>;
   }
-  
-  // Primitive value (e.g. raw ID): try to resolve from options
-  return <span className="truncate">{resolveLabel(value)}</span>;
+
+  // Primitive value (e.g. raw ID): try options → resolver → opaque-ID placeholder → raw
+  const { text, muted } = resolveLabel(value);
+  return <span className={cn('truncate', muted && 'text-muted-foreground')}>{text}</span>;
 }
 
 /**
@@ -868,6 +1191,51 @@ export function registerFieldRenderer(type: string, renderer: React.FC<CellRende
   fieldRegistry.set(type, renderer);
 }
 
+/**
+ * Format hints (e.g. `{ type: 'text', format: 'phone' }`) that should
+ * map to a richer cell renderer than the bare type would imply. The
+ * canonical ObjectStack pattern uses `Field.text({ format: 'phone' })`
+ * for plain text columns that should still render with a tel: link,
+ * `Field.text({ format: 'url' })` for clickable links, etc.
+ *
+ * Only applies when the field's base type is a generic text type;
+ * explicit types like 'phone'/'email'/'currency' already win without
+ * any format hint.
+ */
+const FORMAT_TO_RENDERER: Record<string, string> = {
+  phone: 'phone',
+  tel: 'phone',
+  telephone: 'phone',
+  email: 'email',
+  url: 'url',
+  uri: 'url',
+  link: 'url',
+  currency: 'currency',
+  money: 'currency',
+  percent: 'percent',
+  percentage: 'percent',
+};
+
+const TEXTUAL_BASE_TYPES = new Set(['text', 'textarea', 'string', 'longtext', '']);
+
+/**
+ * Resolve the canonical cell-renderer key for a field. Accepts either a
+ * raw type string (back-compat) or a field-metadata object so that
+ * format hints (`format: 'phone'` etc.) can promote a plain `text`
+ * field to its richer renderer counterpart.
+ */
+export function resolveCellRendererType(fieldOrType: string | { type?: string; format?: string } | null | undefined): string {
+  if (!fieldOrType) return 'text';
+  if (typeof fieldOrType === 'string') return fieldOrType;
+  const baseType = (fieldOrType.type || '').toLowerCase();
+  const formatRaw = fieldOrType.format;
+  const format = typeof formatRaw === 'string' ? formatRaw.toLowerCase() : '';
+  if (format && FORMAT_TO_RENDERER[format] && TEXTUAL_BASE_TYPES.has(baseType)) {
+    return FORMAT_TO_RENDERER[format];
+  }
+  return fieldOrType.type || 'text';
+}
+
 /**
  * Get the appropriate cell renderer for a field type
  */