@object-ui/fields 14.0.0 → 15.0.0

package/src/index.tsx

@@ -8,7 +8,7 @@
 
 import React from 'react';
 import type { FieldMetadata, SelectOptionMetadata } from '@object-ui/types';
-import { ComponentRegistry, percentDisplayValue } from '@object-ui/core';
+import { ComponentRegistry, percentDisplayValue, getRecordDisplayName } from '@object-ui/core';
 import { useLocalization } from '@object-ui/i18n';
 import { Badge, Avatar, AvatarImage, AvatarFallback, Button, Checkbox, EmptyValue, cn } from '@object-ui/components';
 import { Check, X, Copy, Phone as PhoneIcon, MapPin } from 'lucide-react';
@@ -78,6 +78,97 @@ export function pickRecordDisplayName(
   return undefined;
 }
 
+// Module-level cache of referenced-object schemas (keyed by object name) so
+// many lookup cells pointing at the same object trigger ONE metadata fetch.
+type RefSchemaCacheEntry =
+  | { state: 'pending'; promise: Promise<void> }
+  | { state: 'ok'; schema: unknown }
+  | { state: 'err' };
+const refObjectSchemaCache: Map<string, RefSchemaCacheEntry> = new Map();
+
+/**
+ * Fetch (and cache) the referenced object's schema via
+ * `dataSource.getObjectSchema`. Resolves to `undefined` when the data source
+ * doesn't expose schema metadata or the fetch fails — callers fall back to the
+ * key heuristic in that case.
+ */
+async function fetchRefObjectSchema(dataSource: any, referenceTo: string): Promise<any> {
+  const settled = () => {
+    const entry = refObjectSchemaCache.get(referenceTo);
+    return entry?.state === 'ok' ? entry.schema : undefined;
+  };
+  const existing = refObjectSchemaCache.get(referenceTo);
+  if (existing?.state === 'pending') {
+    await existing.promise;
+    return settled();
+  }
+  if (existing) return settled();
+  const getSchema = dataSource?.getObjectSchema;
+  if (typeof getSchema !== 'function') return undefined;
+  const promise = Promise.resolve()
+    .then(() => getSchema.call(dataSource, referenceTo))
+    .then((schema: unknown) => { refObjectSchemaCache.set(referenceTo, { state: 'ok', schema }); })
+    .catch(() => { refObjectSchemaCache.set(referenceTo, { state: 'err' }); });
+  refObjectSchemaCache.set(referenceTo, { state: 'pending', promise });
+  await promise;
+  return settled();
+}
+
+/**
+ * React hook wrapper over {@link fetchRefObjectSchema}: returns the referenced
+ * object's schema once loaded (re-rendering when it lands), `undefined` while
+ * pending or when schema metadata isn't available.
+ */
+function useRefObjectSchema(referenceTo: string | undefined): any {
+  const ctx = React.useContext(_SchemaRendererContext);
+  const dataSource = ctx?.dataSource as any;
+  const [, force] = React.useState(0);
+  const canFetch =
+    !!referenceTo && !!dataSource && typeof dataSource.getObjectSchema === 'function';
+
+  React.useEffect(() => {
+    if (!canFetch) return;
+    const entry = refObjectSchemaCache.get(referenceTo!);
+    if (entry && entry.state !== 'pending') return; // settled before this render
+    let alive = true;
+    fetchRefObjectSchema(dataSource, referenceTo!).then(() => {
+      if (alive) force((n) => n + 1);
+    });
+    return () => { alive = false; };
+  }, [canFetch, referenceTo, dataSource]);
+
+  if (!canFetch) return undefined;
+  const entry = refObjectSchemaCache.get(referenceTo!);
+  return entry?.state === 'ok' ? entry.schema : undefined;
+}
+
+/**
+ * Resolve an expanded/fetched lookup record to its display name the same way
+ * the picker does (issue #2357): explicit `displayField` first, then the
+ * unified ADR-0079 resolver against the referenced object's schema
+ * (`nameField`/`displayNameField` → `titleFormat` → type-aware derivation,
+ * which excludes autonumber). Only when no schema is available does it fall
+ * back to {@link pickRecordDisplayName}, whose `_number`/`_code` suffix scan
+ * can otherwise surface an autonumber (`0001`) over the record's real name.
+ */
+function resolveLookupRecordName(
+  record: Record<string, unknown> | null | undefined,
+  refSchema?: any,
+  displayField?: string,
+): string | undefined {
+  if (!record || typeof record !== 'object') return undefined;
+  if (refSchema) {
+    const resolved = getRecordDisplayName(refSchema, record, { titleField: displayField });
+    // Stop short of the resolver's `Record #<id>` / `Untitled` floor so the
+    // cell keeps its own id-placeholder handling for nameless records.
+    const id = (record as any).id ?? (record as any)._id;
+    const isFloor =
+      resolved === 'Untitled' || (id != null && resolved === `Record #${id}`);
+    if (!isFloor && resolved) return resolved;
+  }
+  return pickRecordDisplayName(record, displayField);
+}
+
 /**
  * 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
@@ -101,7 +192,11 @@ export function isLikelyOpaqueId(v: unknown): boolean {
  * 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 {
+function useLookupName(
+  referenceTo: string | undefined,
+  value: unknown,
+  displayField?: string,
+): string | undefined {
   const ctx = React.useContext(_SchemaRendererContext);
   const dataSource = ctx?.dataSource;
   const [, force] = React.useState(0);
@@ -112,7 +207,12 @@ function useLookupName(referenceTo: string | undefined, value: unknown): string
     typeof dataSource.find === 'function' &&
     (typeof value === 'string' || typeof value === 'number') &&
     value !== '';
-  const cacheKey = isResolvable ? `${referenceTo}:${String(value)}` : '';
+  // The preferred display field is part of the cache identity: two columns
+  // targeting the same record with different `display_field`s must not
+  // serve each other's cached name (#2926 ⑧).
+  const cacheKey = isResolvable
+    ? `${referenceTo}:${String(value)}:${displayField ?? ''}`
+    : '';
 
   React.useEffect(() => {
     if (!isResolvable) return;
@@ -135,7 +235,11 @@ function useLookupName(referenceTo: string | undefined, value: unknown): string
             : (result?.value || result?.data || []);
           record = records[0];
         }
-        const name = pickRecordDisplayName(record);
+        // Resolve through the referenced object's schema (nameField /
+        // titleFormat) so the chip agrees with the picker — the bare key
+        // heuristic alone can surface an autonumber over the real name.
+        const schema = await fetchRefObjectSchema(dataSource, referenceTo!);
+        const name = resolveLookupRecordName(record, schema, displayField);
         lookupNameCache.set(cacheKey, { state: 'ok', name });
       } catch {
         lookupNameCache.set(cacheKey, { state: 'err' });
@@ -144,7 +248,7 @@ function useLookupName(referenceTo: string | undefined, value: unknown): string
     })();
 
     lookupNameCache.set(cacheKey, { state: 'pending', promise });
-  }, [cacheKey, isResolvable, referenceTo, value, dataSource]);
+  }, [cacheKey, isResolvable, referenceTo, value, displayField, dataSource]);
 
   if (!isResolvable) return undefined;
   const entry = lookupNameCache.get(cacheKey);
@@ -156,14 +260,28 @@ function useLookupName(referenceTo: string | undefined, value: unknown): string
  * default when no I18nProvider is available or when the key is missing.
  */
 function useFieldLabel() {
+  // useObjectTranslation is provider-safe (its context read is optional and
+  // react-i18next falls back to the global instance), so no try/catch —
+  // wrapping a hook call in try/catch violates rules-of-hooks: a throw after
+  // some hooks ran would desync hook order on the next render.
+  const { t } = useObjectTranslation();
+  return (key: string, fallback: string) => {
+    const v = t(key);
+    return !v || v === key ? fallback : v;
+  };
+}
+
+/**
+ * Raw translate fn (with interpolation params) for cell-level strings, or
+ * undefined when no I18nProvider is mounted — callers keep their English
+ * fallback in that case.
+ */
+function useFieldTranslate(): ((key: string, params?: Record<string, unknown>) => string) | undefined {
   try {
     const { t } = useObjectTranslation();
-    return (key: string, fallback: string) => {
-      const v = t(key);
-      return !v || v === key ? fallback : v;
-    };
+    return t as (key: string, params?: Record<string, unknown>) => string;
   } catch {
-    return (_k: string, fallback: string) => fallback;
+    return undefined;
   }
 }
 
@@ -361,14 +479,43 @@ export function humanizeLabel(value: string): string {
   return value.replace(/[_-]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 }
 
+/** Options shared by {@link formatDate} / {@link formatRelativeDate}. */
+export interface DateDisplayOptions {
+  dueLike?: boolean;
+  /** BCP-47 display locale (ADR-0053 tenant default); falls back to the runtime locale. */
+  locale?: string;
+  /** i18n translate fn for phrases `Intl` can't produce (the "Overdue Nd" wording). */
+  t?: (key: string, params?: Record<string, unknown>) => string;
+}
+
 /**
- * Format date as relative time (e.g., "2 days ago", "Today", "Overdue 3d")
+ * Localized day-granularity relative phrase ("Tomorrow", "3 days ago", "明天",
+ * "3天前"), sentence-cased for locales whose `Intl` output starts lowercase.
+ */
+function formatRelativeDays(diffDays: number, locale?: string): string {
+  try {
+    const phrase = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(diffDays, 'day');
+    return phrase.charAt(0).toUpperCase() + phrase.slice(1);
+  } catch {
+    // Invalid locale tag — degrade to English rather than crash the cell.
+    if (diffDays === 0) return 'Today';
+    if (diffDays === 1) return 'Tomorrow';
+    if (diffDays === -1) return 'Yesterday';
+    return diffDays > 0 ? `In ${diffDays} days` : `${Math.abs(diffDays)} days ago`;
+  }
+}
+
+/**
+ * Format date as relative time (e.g., "3 days ago", "Today", "Overdue 3d"),
+ * localized via `Intl.RelativeTimeFormat` (objectstack-ai/framework#3040).
  *
  * `dueLike` gates the "Overdue" wording — a past `start_date`/`created_at`
  * isn't overdue, only a past due/deadline-semantic field is. Non-due-like
- * past dates render as "Nd ago" instead.
+ * past dates render as plain "N days ago" instead. The overdue phrase has no
+ * `Intl` equivalent, so it resolves through `options.t` (key
+ * `fields.relativeDate.overdue`) with an English fallback.
  */
-export function formatRelativeDate(value: string | Date | number, options?: { dueLike?: boolean }): string {
+export function formatRelativeDate(value: string | Date | number, options?: DateDisplayOptions): 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 '—';
@@ -379,22 +526,22 @@ export function formatRelativeDate(value: string | Date | number, options?: { du
   const diffMs = startOfDate.getTime() - startOfToday.getTime();
   const diffDays = Math.round(diffMs / (1000 * 60 * 60 * 24));
 
-  if (diffDays === 0) return 'Today';
-  if (diffDays === 1) return 'Tomorrow';
-  if (diffDays === -1) return 'Yesterday';
-  if (diffDays < -1) {
+  // Beyond the ±7-day window, fall back to the absolute (already localized) form.
+  if (diffDays < -7 || diffDays > 7) return formatDate(date, undefined, options);
+
+  if (diffDays < -1 && options?.dueLike) {
     const absDays = Math.abs(diffDays);
-    if (absDays <= 7) return options?.dueLike ? `Overdue ${absDays}d` : `${absDays}d ago`;
-    return formatDate(date);
+    const key = 'fields.relativeDate.overdue';
+    const translated = options.t?.(key, { count: absDays });
+    return translated && translated !== key ? translated : `Overdue ${absDays}d`;
   }
-  if (diffDays > 1 && diffDays <= 7) return `In ${diffDays} days`;
-  return formatDate(date);
+  return formatRelativeDays(diffDays, options?.locale);
 }
 
 /**
  * Format date value
  */
-export function formatDate(value: string | Date | number, style?: string, options?: { dueLike?: boolean }): string {
+export function formatDate(value: string | Date | number, style?: string, options?: DateDisplayOptions): 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 '—';
@@ -417,7 +564,7 @@ export function formatDate(value: string | Date | number, style?: string, option
   // verbose "2026年7月21日" form crowds cards and table cells. Past- /
   // future-year dates keep the year so users can disambiguate.
   const isCurrentYear = date.getFullYear() === new Date().getFullYear();
-  return date.toLocaleDateString(undefined, {
+  return date.toLocaleDateString(options?.locale, {
     year: isCurrentYear ? undefined : 'numeric',
     month: 'short',
     day: 'numeric',
@@ -482,14 +629,16 @@ export function NumberCellRenderer({ value, field }: CellRendererProps): React.R
  * Currency field cell renderer
  */
 export function CurrencyCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
+  // Hooks before the empty-value early return — a value flipping between
+  // null and set must not change the hook count between renders.
+  const { currency: tenantCurrency } = useLocalization();
   if (value == null) return <EmptyValue />;
-  
+
   const safe = coerceToSafeValue(value);
   // Resolve the display currency via the shared precedence: field `currency` →
   // `currencyConfig.defaultCurrency` → the tenant default (ADR-0053). When none
   // is known, render a plain number — never a guessed symbol (silently assuming
   // USD mis-displays non-USD orgs, e.g. RMB amounts shown as $).
-  const { currency: tenantCurrency } = useLocalization();
   const currency = resolveFieldCurrency(field as any, tenantCurrency);
   const num = Number(safe);
   const formatted = !isNaN(num)
@@ -598,6 +747,8 @@ export function BooleanCellRenderer({ value, field }: CellRendererProps): React.
  * Date field cell renderer
  */
 export function DateCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
+  const { locale } = useLocalization();
+  const t = useFieldTranslate();
   if (!value) return <EmptyValue />;
   const safe = coerceToSafeValue(value);
   const dateField = field as any;
@@ -610,7 +761,7 @@ export function DateCellRenderer({ value, field }: CellRendererProps): React.Rea
   const dueLike =
     dateField?.dueLike === true ||
     /(^|_)(due|deadline|expires?|expiry|expiration|expected_close|target_close|sla|return_by|renewal|next_action)(_|$)/.test(fieldName);
-  const formatted = formatDate(safe as string | Date, style, { dueLike });
+  const formatted = formatDate(safe as string | Date, style, { dueLike, locale, t });
 
   const date = safe != null ? new Date(safe as string | number) : null;
   const isValidDate = date !== null && !isNaN(date.getTime());
@@ -946,13 +1097,18 @@ export function SelectCellRenderer({ value, field }: CellRendererProps): React.R
     }
 
     const colorClasses = getBadgeColorClasses(option?.color, val);
+    // max-w-full + inner truncate: in bounded containers (detail highlight
+    // strip columns, grid cells) an overlong label used to clip mid-glyph at
+    // the container edge; now the badge shrinks and ellipsizes, with the full
+    // label on hover.
     return (
       <Badge
         key={key}
         variant="outline"
-        className={colorClasses}
+        className={cn('max-w-full min-w-0', colorClasses)}
+        title={label}
       >
-        {label}
+        <span className="truncate">{label}</span>
       </Badge>
     );
   };
@@ -973,11 +1129,12 @@ export function SelectCellRenderer({ value, field }: CellRendererProps): React.R
  * Email field cell renderer
  */
 export function EmailCellRenderer({ value }: CellRendererProps): React.ReactElement {
+  // Hooks before the empty-value early return (rules-of-hooks).
+  const label = useFieldLabel();
+  const [copied, setCopied] = React.useState(false);
   if (!value) return <EmptyValue />;
 
-  const label = useFieldLabel();
   const safe = String(coerceToSafeValue(value) ?? '');
-  const [copied, setCopied] = React.useState(false);
 
   const handleCopy = (e: React.MouseEvent) => {
     e.stopPropagation();
@@ -1047,11 +1204,12 @@ export function UrlCellRenderer({ value }: CellRendererProps): React.ReactElemen
  * Phone field cell renderer
  */
 export function PhoneCellRenderer({ value }: CellRendererProps): React.ReactElement {
+  // Hooks before the empty-value early return (rules-of-hooks).
+  const label = useFieldLabel();
+  const [copied, setCopied] = React.useState(false);
   if (!value) return <EmptyValue />;
 
-  const label = useFieldLabel();
   const safe = String(coerceToSafeValue(value) ?? '');
-  const [copied, setCopied] = React.useState(false);
 
   const handleCopy = (e: React.MouseEvent) => {
     e.stopPropagation();
@@ -1167,6 +1325,11 @@ export function ImageCellRenderer({ value }: CellRendererProps): React.ReactElem
  * 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.
+ *
+ * Record → name resolution (1 and 3) goes through the referenced object's
+ * schema when the data source exposes it (`displayField` → nameField/titleFormat
+ * → derivation, see {@link resolveLookupRecordName}), so the chip and the
+ * picker agree (issue #2357).
  */
 export function LookupCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
   // ObjectStack object metadata uses `reference` for the lookup target while the
@@ -1178,6 +1341,19 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
     (field as { reference_to?: string }).reference_to ||
     (field as { reference?: string }).reference;
 
+  // Explicit author-chosen display field on the lookup — beats every resolver.
+  // ObjectGrid forwards `display_field` on the column meta (RELATIONAL_META_KEYS)
+  // the same way it forwards `reference` (#2926 ⑧).
+  const displayField =
+    (field as { display_field?: string }).display_field ||
+    (field as { displayField?: string }).displayField ||
+    (field as { reference_field?: string }).reference_field ||
+    undefined;
+
+  // Referenced object's schema (nameField / titleFormat) so expanded records
+  // resolve through the same unified resolver as the picker (issue #2357).
+  const refSchema = useRefObjectSchema(referenceTo);
+
   // 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 = (() => {
@@ -1199,7 +1375,7 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
   })();
 
   // Always call the hook (rules of hooks). It safely no-ops when inputs are missing.
-  const resolvedName = useLookupName(referenceTo, primaryPrimitiveId);
+  const resolvedName = useLookupName(referenceTo, primaryPrimitiveId, displayField);
 
   if (value == null || value === '') return <EmptyValue />;
 
@@ -1209,15 +1385,18 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
   if (typeof value === 'string') {
     const s = value.trim();
     if (s.startsWith('{') && s.endsWith('}')) {
+      // Compute inside try, render outside — constructing JSX in a try/catch
+      // doesn't catch its render errors anyway (react-hooks/error-boundaries).
+      let parsedDisplay = '';
       try {
         const parsed = JSON.parse(s) as Record<string, unknown>;
         if (parsed && typeof parsed === 'object') {
-          const display =
-            pickRecordDisplayName(parsed) ||
+          parsedDisplay =
+            resolveLookupRecordName(parsed, refSchema, displayField) ||
             String(parsed.externalId ?? parsed.id ?? parsed._id ?? '');
-          if (display) return <span className="truncate">{display}</span>;
         }
       } catch { /* not JSON — fall through to normal resolution */ }
+      if (parsedDisplay) return <span className="truncate">{parsedDisplay}</span>;
     }
   }
 
@@ -1225,7 +1404,8 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
   // (e.g. { id, name }). Render its display name directly — no fetch needed.
   if (!Array.isArray(value) && typeof value === 'object') {
     const obj = value as Record<string, unknown>;
-    const display = pickRecordDisplayName(obj) || String(obj.id || obj._id || '');
+    const display =
+      resolveLookupRecordName(obj, refSchema, displayField) || String(obj.id || obj._id || '');
     if (display) {
       return <span className="truncate">{display}</span>;
     }
@@ -1259,7 +1439,7 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
           let label: string;
           let muted = false;
           if (item != null && typeof item === 'object') {
-            label = pickRecordDisplayName(item as Record<string, unknown>) || String((item as any).id || (item as any)._id || '[Object]');
+            label = resolveLookupRecordName(item as Record<string, unknown>, refSchema, displayField) || String((item as any).id || (item as any)._id || '[Object]');
           } else {
             const r = resolveLabel(item);
             label = r.text;
@@ -1285,7 +1465,7 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
 
   if (typeof value === 'object' && value !== null) {
     const label =
-      pickRecordDisplayName(value as Record<string, unknown>) ||
+      resolveLookupRecordName(value as Record<string, unknown>, refSchema, displayField) ||
       String((value as any).id || (value as any)._id || '[Object]');
     return <span className="truncate">{label}</span>;
   }

package/src/standard-widgets.test.tsx

@@ -104,6 +104,41 @@ describe('Standard Field Widgets', () => {
       );
       expect(container.textContent).toBe('99.9');
     });
+
+    it('should surface metadata min/max on the input (objectui#2572)', () => {
+      render(
+        <NumberField
+          value={5}
+          onChange={mockOnChange}
+          field={{ type: 'number', min: 0, max: 100 } as any}
+        />
+      );
+      const input = screen.getByRole('spinbutton');
+      expect(input).toHaveAttribute('min', '0');
+      expect(input).toHaveAttribute('max', '100');
+    });
+
+    it('should step by 1 for scale: 0 (whole numbers), not "any"', () => {
+      render(
+        <NumberField
+          value={5}
+          onChange={mockOnChange}
+          field={{ type: 'number', scale: 0 } as any}
+        />
+      );
+      expect(screen.getByRole('spinbutton')).toHaveAttribute('step', '1');
+    });
+
+    it('should honor an explicit metadata step over the scale-derived one', () => {
+      render(
+        <NumberField
+          value={5}
+          onChange={mockOnChange}
+          field={{ type: 'number', scale: 2, step: 5 } as any}
+        />
+      );
+      expect(screen.getByRole('spinbutton')).toHaveAttribute('step', '5');
+    });
   });
 
   describe('TextField', () => {

package/src/widgets/CurrencyField.tsx

@@ -81,6 +81,11 @@ export function CurrencyField({ value, onChange, field, readonly, errorMessage,
         placeholder={currencyField?.placeholder || '0.00'}
         disabled={readonly || props.disabled}
         className={`${symbol ? 'pl-8' : ''} ${className || ''}`}
+        // Surface the field's declared range (e.g. `min: 0` on a budget) so the
+        // browser's spinner/keyboard affordances respect it (objectui#2572);
+        // server-side validation still owns enforcement.
+        min={typeof currencyField?.min === 'number' ? currencyField.min : undefined}
+        max={typeof currencyField?.max === 'number' ? currencyField.max : undefined}
         step={Math.pow(10, -precision).toFixed(precision)}
         aria-invalid={!!errorMessage}
       />