@object-ui/fields 4.0.8 → 4.0.10

package/dist/packages/fields/src/index.d.ts

@@ -1,5 +1,11 @@
 import { default as React } from 'react';
 import { FieldMetadata } from '../../types/src';
+/**
+ * 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 declare function isLikelyOpaqueId(v: unknown): boolean;
 /**
  * Cell renderer props
  */
@@ -88,8 +94,35 @@ export declare function DateCellRenderer({ value, field }: CellRendererProps): R
  * DateTime field cell renderer (Airtable-style with date and time visually separated)
  */
 export declare function DateTimeCellRenderer({ value }: CellRendererProps): React.ReactElement;
+export declare function getBadgeColorClasses(color?: string, val?: unknown): string;
+/**
+ * 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 declare function getSemanticColorName(color?: string, val?: unknown): string | undefined;
 /**
- * Select field cell renderer (with badges)
+ * 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 declare function getSemanticHex(name?: string, fallback?: string): string;
+/**
+ * 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 declare function SelectCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
 /**
@@ -113,7 +146,14 @@ export declare function FileCellRenderer({ value, field }: CellRendererProps): R
  */
 export declare function ImageCellRenderer({ value }: CellRendererProps): React.ReactElement;
 /**
- * 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 declare function LookupCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/fields",
-  "version": "4.0.8",
+  "version": "4.0.10",
   "description": "Field renderers and registry for Object UI",
   "license": "MIT",
   "type": "module",
@@ -27,12 +27,12 @@
     "clsx": "^2.1.1",
     "lucide-react": "^1.14.0",
     "tailwind-merge": "^3.6.0",
-    "@object-ui/components": "4.0.8",
-    "@object-ui/core": "4.0.8",
-    "@object-ui/i18n": "4.0.8",
-    "@object-ui/providers": "4.0.8",
-    "@object-ui/react": "4.0.8",
-    "@object-ui/types": "4.0.8"
+    "@object-ui/components": "4.0.10",
+    "@object-ui/core": "4.0.10",
+    "@object-ui/i18n": "4.0.10",
+    "@object-ui/providers": "4.0.10",
+    "@object-ui/react": "4.0.10",
+    "@object-ui/types": "4.0.10"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/index.tsx

@@ -9,9 +9,106 @@
 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
@@ -328,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}
@@ -560,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[] = [
@@ -579,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, '_');
@@ -591,11 +704,66 @@ 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 />;
 
@@ -610,42 +778,47 @@ export function SelectCellRenderer({ value, field }: CellRendererProps): React.R
     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 = findOption(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 = findOption(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);
 }
 
 /**
@@ -825,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 };
+    }
+    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 String(val);
+    return { text: String(val), muted: false };
   };
 
   if (Array.isArray(value)) {
@@ -847,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>
@@ -864,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>;
 }
 
 /**