@object-ui/fields 6.2.2 → 7.0.0

package/src/widgets/MultiSelectField.tsx

@@ -0,0 +1,59 @@
+import React from 'react';
+import { Badge, EmptyValue, cn } from '@object-ui/components';
+import { FieldWidgetProps } from './types';
+
+interface Option { label: string; value: string; color?: string }
+
+/**
+ * MultiSelectField - select zero or more values from a fixed option set.
+ *
+ * Renders the configured options as toggleable chips. The stored value is a
+ * string[] (the selected option values). Used for the `multiselect` field type.
+ */
+export function MultiSelectField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string[]>) {
+  const config = (field || (props as any).schema) as any;
+  const options: Option[] = config?.options || [];
+  const selected: string[] = Array.isArray(value) ? value : value == null ? [] : [value as unknown as string];
+
+  if (readonly) {
+    if (selected.length === 0) return <EmptyValue />;
+    return (
+      <div className="flex flex-wrap gap-1">
+        {selected.map((v) => {
+          const opt = options.find((o) => o.value === v);
+          return <Badge key={v} variant="outline">{opt?.label || v}</Badge>;
+        })}
+      </div>
+    );
+  }
+
+  const toggle = (v: string) => {
+    const next = selected.includes(v) ? selected.filter((x) => x !== v) : [...selected, v];
+    onChange(next);
+  };
+
+  return (
+    <div className={cn('flex flex-wrap gap-1.5', className)}>
+      {options.map((opt) => {
+        const active = selected.includes(opt.value);
+        return (
+          <button
+            type="button"
+            key={opt.value}
+            onClick={() => toggle(opt.value)}
+            disabled={(props as any).disabled}
+            aria-pressed={active}
+            className={cn(
+              'rounded-full border px-3 py-1 text-sm transition-colors',
+              active
+                ? 'border-primary bg-primary text-primary-foreground'
+                : 'border-input bg-background text-foreground hover:bg-accent',
+            )}
+          >
+            {opt.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/widgets/PercentField.tsx

@@ -11,18 +11,30 @@ export function PercentField({ value, onChange, field, readonly, errorMessage, c
   const percentField = (field || (props as any).schema) as any;
   const precision = percentField?.precision ?? 2;
 
+  // Convention detection. A field declaring `max > 1` (e.g. `max: 100`) stores
+  // WHOLE-NUMBER percents (0–100); otherwise values are FRACTIONS (0–1) shown
+  // as 0–100%. This matches the read-side formatter so the edit widget agrees
+  // with display — and, crucially, keeps the rendered <input> within its `max`
+  // (a whole-number 50 must show "50", not "5000", or HTML5 constraint
+  // validation marks the field `:invalid` and blocks the whole form's submit).
+  const maxAttr = typeof percentField?.max === 'number' ? (percentField.max as number) : undefined;
+  const whole = maxAttr != null && maxAttr > 1;
+  const toDisplay = (v: number) => (whole ? v : v * 100);
+  const fromDisplay = (n: number) => (whole ? n : n / 100);
+  const sliderMax = whole ? maxAttr! : 100;
+
   if (readonly) {
     if (value == null) return <EmptyValue />;
     return (
       <span className="text-sm font-medium tabular-nums">
-        {(value * 100).toFixed(precision)}%
+        {toDisplay(value).toFixed(precision)}%
       </span>
     );
   }
 
-  // Convert between stored value (0-1) and display value (0-100)
-  const displayValue = value != null ? (value * 100) : '';
-  const sliderValue = value != null ? value * 100 : 0;
+  // Convert between stored value and 0–100 display value
+  const displayValue = value != null ? toDisplay(value) : '';
+  const sliderValue = value != null ? toDisplay(value) : 0;
 
   const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     if (e.target.value === '') {
@@ -30,7 +42,7 @@ export function PercentField({ value, onChange, field, readonly, errorMessage, c
       return;
     }
     const parsed = parseFloat(e.target.value);
-    const val = isNaN(parsed) ? null : parsed / 100;
+    const val = isNaN(parsed) ? null : fromDisplay(parsed);
     onChange(val as any);
   };
 
@@ -41,7 +53,7 @@ export function PercentField({ value, onChange, field, readonly, errorMessage, c
       return;
     }
     const raw = values[0];
-    const nextValue = typeof raw === 'number' ? raw / 100 : null;
+    const nextValue = typeof raw === 'number' ? fromDisplay(raw) : null;
     onChange(nextValue as any);
   };
 
@@ -70,7 +82,7 @@ export function PercentField({ value, onChange, field, readonly, errorMessage, c
         value={[sliderValue]}
         onValueChange={handleSliderChange}
         min={0}
-        max={100}
+        max={sliderMax}
         step={sliderStep}
         disabled={readonly || props.disabled}
         className="w-full"

package/src/widgets/RadioField.tsx

@@ -0,0 +1,41 @@
+import React, { useId } from 'react';
+import { RadioGroup, RadioGroupItem, Label, EmptyValue } from '@object-ui/components';
+import { FieldWidgetProps } from './types';
+
+interface Option { label: string; value: string }
+
+/**
+ * RadioField - choose exactly one value from a fixed option set, rendered as a
+ * radio group. The stored value is the selected option value (string). Used for
+ * the `radio` field type.
+ */
+export function RadioField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string>) {
+  const config = (field || (props as any).schema) as any;
+  const options: Option[] = config?.options || [];
+  const groupId = useId();
+
+  if (readonly) {
+    if (value == null || value === '') return <EmptyValue />;
+    const opt = options.find((o) => o.value === value);
+    return <span className="text-sm">{opt?.label || String(value)}</span>;
+  }
+
+  return (
+    <RadioGroup
+      value={value ?? ''}
+      onValueChange={onChange}
+      disabled={(props as any).disabled}
+      className={className}
+    >
+      {options.map((opt) => {
+        const id = `${groupId}-${opt.value}`;
+        return (
+          <div key={opt.value} className="flex items-center space-x-2">
+            <RadioGroupItem value={opt.value} id={id} />
+            <Label htmlFor={id} className="font-normal">{opt.label}</Label>
+          </div>
+        );
+      })}
+    </RadioGroup>
+  );
+}

package/src/widgets/RecordPickerDialog.tsx

@@ -38,6 +38,7 @@ import {
   X,
 } from 'lucide-react';
 import type { DataSource, QueryParams, LookupColumnDef, LookupFilterDef } from '@object-ui/types';
+import { useFieldTranslation } from './useFieldTranslation';
 
 /** Default page size for the Record Picker dialog */
 const DEFAULT_PAGE_SIZE = 10;
@@ -144,7 +145,7 @@ function fieldToLabel(field: string): string {
  * QueryParams.$filter.  Supports operator mapping for eq/ne/gt/lt/gte/lte/
  * contains/in/notIn.
  */
-function lookupFiltersToRecord(
+export function lookupFiltersToRecord(
   filters: LookupFilterDef[],
 ): Record<string, any> {
   const result: Record<string, any> = {};
@@ -336,6 +337,7 @@ export function RecordPickerDialog({
   renderFilterBar,
   renderGrid,
 }: RecordPickerDialogProps) {
+  const { t } = useFieldTranslation();
   const [records, setRecords] = useState<any[]>([]);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -801,7 +803,7 @@ export function RecordPickerDialog({
                 onValueChange={v => handleFilterChange(col.field, v)}
               >
                 <SelectTrigger className="h-8 text-xs">
-                  <SelectValue placeholder={`Filter ${label}`} />
+                  <SelectValue placeholder={t('lookup.filterPlaceholder', { label })} />
                 </SelectTrigger>
                 <SelectContent>
                   {col.options?.map(opt => (
@@ -821,7 +823,7 @@ export function RecordPickerDialog({
                 type="number"
                 className="h-8 text-xs"
                 value={val ?? ''}
-                placeholder={`Filter ${label}`}
+                placeholder={t('lookup.filterPlaceholder', { label })}
                 onChange={e => {
                   const raw = e.target.value;
                   handleFilterChange(col.field, raw === '' ? '' : Number(raw));
@@ -850,7 +852,7 @@ export function RecordPickerDialog({
                   checked={Boolean(val)}
                   onCheckedChange={checked => handleFilterChange(col.field, Boolean(checked))}
                 />
-                <span className="text-xs text-muted-foreground">Yes</span>
+                <span className="text-xs text-muted-foreground">{t('lookup.yes')}</span>
               </div>
             </div>
           );
@@ -862,7 +864,7 @@ export function RecordPickerDialog({
               <Input
                 className="h-8 text-xs"
                 value={val ?? ''}
-                placeholder={`Filter ${label}`}
+                placeholder={t('lookup.filterPlaceholder', { label })}
                 onChange={e => handleFilterChange(col.field, e.target.value)}
               />
             </div>
@@ -896,7 +898,7 @@ export function RecordPickerDialog({
         <div className="relative rounded-md border bg-muted/30 mb-3">
           <Search className="absolute left-3 top-1/2 -translate-y-1/2 size-4 text-muted-foreground" />
           <Input
-            placeholder="Search..."
+            placeholder={t('table.search')}
             value={searchQuery}
             onChange={(e) => handleSearchChange(e.target.value)}
             className="pl-9 border-0 bg-transparent shadow-none focus-visible:ring-0"
@@ -936,7 +938,7 @@ export function RecordPickerDialog({
                     onClick={() => setFilterBarOpen(prev => !prev)}
                   >
                     <SlidersHorizontal className="size-3.5" />
-                    Filters
+                    {t('lookup.filters')}
                     {activeFilterCount > 0 && (
                       <span className="inline-flex h-5 min-w-[20px] items-center justify-center rounded-full bg-primary/10 px-1 text-xs font-medium text-primary">
                         {activeFilterCount}
@@ -952,7 +954,7 @@ export function RecordPickerDialog({
                       onClick={handleFilterClear}
                     >
                       <X className="size-3" />
-                      Clear
+                      {t('lookup.clear')}
                     </Button>
                   )}
                 </div>
@@ -979,7 +981,7 @@ export function RecordPickerDialog({
               onClick={() => fetchRecords(searchQuery || undefined, currentPage, currentSort)}
               type="button"
             >
-              Retry
+              {t('lookup.retry')}
             </Button>
           </div>
         )}
@@ -1046,7 +1048,7 @@ export function RecordPickerDialog({
             {/* Empty state */}
             {!loading && !error && records.length === 0 && (
               <div className="py-8 text-center">
-                <p className="text-sm text-muted-foreground">No records found</p>
+                <p className="text-sm text-muted-foreground">{t('lookup.noRecords')}</p>
               </div>
             )}
 
@@ -1054,6 +1056,8 @@ export function RecordPickerDialog({
             {!error && records.length > 0 && (
               <div
                 className="relative flex-1 overflow-auto min-h-0 border rounded-md"
+                aria-busy={loading || undefined}
+                data-state={loading ? 'loading' : 'idle'}
                 tabIndex={0}
                 onKeyDown={handleTableKeyDown}
                 role="grid"
@@ -1151,8 +1155,8 @@ export function RecordPickerDialog({
                 data-testid="record-picker-pagination"
               >
                 <span>
-                  {totalCount} {totalCount === 1 ? 'record' : 'records'}
-                  {totalPages > 1 && ` · Page ${currentPage} of ${totalPages}`}
+                  {totalCount === 1 ? t('lookup.recordCountOne') : t('lookup.recordCount', { count: totalCount })}
+                  {totalPages > 1 && ` · ${t('lookup.pageOf', { current: currentPage, total: totalPages })}`}
                 </span>
                 {totalPages > 1 && (
                   <div className="flex items-center gap-1.5">
@@ -1163,7 +1167,7 @@ export function RecordPickerDialog({
                       onClick={handlePrevPage}
                       disabled={currentPage <= 1}
                       type="button"
-                      aria-label="Previous page"
+                      aria-label={t('lookup.prevPage')}
                     >
                       <ChevronLeft className="size-4" />
                     </Button>
@@ -1173,7 +1177,7 @@ export function RecordPickerDialog({
                       value={pageJumpValue}
                       onChange={e => setPageJumpValue(e.target.value)}
                       onKeyDown={handlePageJump}
-                      aria-label="Jump to page"
+                      aria-label={t('lookup.jumpToPage')}
                       data-testid="record-picker-page-jump"
                     />
                     <Button
@@ -1183,7 +1187,7 @@ export function RecordPickerDialog({
                       onClick={handleNextPage}
                       disabled={currentPage >= totalPages}
                       type="button"
-                      aria-label="Next page"
+                      aria-label={t('lookup.nextPage')}
                     >
                       <ChevronRight className="size-4" />
                     </Button>
@@ -1199,14 +1203,14 @@ export function RecordPickerDialog({
           <DialogFooter>
             <div className="flex items-center gap-2 w-full justify-between">
               <span className="text-sm text-muted-foreground">
-                {pendingSelection.size} selected
+                {t('table.selected', { count: pendingSelection.size })}
               </span>
               <div className="flex gap-2">
                 <Button variant="outline" type="button" onClick={() => onOpenChange(false)}>
-                  Cancel
+                  {t('common.cancel')}
                 </Button>
                 <Button type="button" onClick={handleConfirm}>
-                  Confirm
+                  {t('common.confirm')}
                 </Button>
               </div>
             </div>

package/src/widgets/SelectField.tsx

@@ -19,6 +19,11 @@ export function SelectField({ value, onChange, field, readonly, ...props }: Fiel
   const config = (field || (props as any).schema) as SelectFieldMetadata;
   const options = config?.options || [];
   const { t } = useFieldTranslation();
+  // Stable hook for automation/e2e — react-hook-form + Radix Select cannot be
+  // driven by synthetic DOM events, so e2e must target the trigger/options by a
+  // deterministic testid keyed on the field name. `props.name` is the
+  // react-hook-form field name spread in by the form renderer (FormField).
+  const fieldName = (props as any).name || (config as any)?.name || props.id || '';
 
   if (readonly) {
     const option = options.find((o) => o.value === value);
@@ -26,6 +31,22 @@ export function SelectField({ value, onChange, field, readonly, ...props }: Fiel
     return display ? <span className="text-sm">{display}</span> : <EmptyValue />;
   }
 
+  // A select with no options is unfillable — a silently-empty Radix dropdown
+  // reads as "broken widget" and hides the real cause (the field metadata has
+  // no `options`). Surface a legible empty state instead, without needing to
+  // open the popover. Mirrors the inline form renderer's behaviour
+  // (see plugin form `renderFieldComponent`'s `case 'select'`).
+  if (options.length === 0) {
+    return (
+      <div
+        data-testid={fieldName ? `select-empty-${fieldName}` : undefined}
+        className="flex h-9 w-full items-center rounded-md border border-input bg-muted/30 px-3 py-2 text-sm text-muted-foreground"
+      >
+        No options available
+      </div>
+    );
+  }
+
   return (
     <Select 
       {...props}
@@ -33,12 +54,12 @@ export function SelectField({ value, onChange, field, readonly, ...props }: Fiel
       onValueChange={onChange}
       disabled={readonly || props.disabled}
     >
-      <SelectTrigger className={props.className} id={props.id}>
+      <SelectTrigger className={props.className} id={props.id} data-testid={fieldName ? `select-trigger-${fieldName}` : undefined}>
         <SelectValue placeholder={config?.placeholder || t('common.selectOption')} />
       </SelectTrigger>
       <SelectContent position="popper">
         {options.map((option) => (
-          <SelectItem key={option.value} value={option.value}>
+          <SelectItem key={option.value} value={option.value} data-testid={`select-option-${option.value}`}>
             {option.label}
           </SelectItem>
         ))}

package/src/widgets/TagsField.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import { Badge, Input, EmptyValue, cn } from '@object-ui/components';
+import { FieldWidgetProps } from './types';
+
+/**
+ * TagsField - free-form list of string tags. Type a value and press Enter (or
+ * comma) to add it; click a tag's × to remove it. The stored value is a
+ * string[]. Used for the `tags` field type.
+ */
+export function TagsField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string[]>) {
+  const tags: string[] = Array.isArray(value) ? value : value == null ? [] : [value as unknown as string];
+  const [draft, setDraft] = React.useState('');
+
+  if (readonly) {
+    if (tags.length === 0) return <EmptyValue />;
+    return (
+      <div className="flex flex-wrap gap-1">
+        {tags.map((t) => <Badge key={t} variant="secondary">{t}</Badge>)}
+      </div>
+    );
+  }
+
+  const addTag = (raw: string) => {
+    const t = raw.trim();
+    if (!t || tags.includes(t)) return;
+    onChange([...tags, t]);
+    setDraft('');
+  };
+
+  const removeTag = (t: string) => onChange(tags.filter((x) => x !== t));
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter' || e.key === ',') {
+      e.preventDefault();
+      addTag(draft);
+    } else if (e.key === 'Backspace' && draft === '' && tags.length > 0) {
+      removeTag(tags[tags.length - 1]);
+    }
+  };
+
+  return (
+    <div className={cn('flex flex-wrap items-center gap-1.5 rounded-md border border-input bg-background p-1.5', className)}>
+      {tags.map((t) => (
+        <Badge key={t} variant="secondary" className="gap-1">
+          {t}
+          <button
+            type="button"
+            onClick={() => removeTag(t)}
+            className="ml-0.5 rounded-full text-muted-foreground hover:text-foreground"
+            aria-label={`Remove ${t}`}
+          >
+            ×
+          </button>
+        </Badge>
+      ))}
+      <Input
+        value={draft}
+        onChange={(e) => setDraft(e.target.value)}
+        onKeyDown={onKeyDown}
+        onBlur={() => addTag(draft)}
+        disabled={(props as any).disabled}
+        placeholder={tags.length === 0 ? '输入后回车添加…' : ''}
+        className="h-7 flex-1 border-0 bg-transparent p-0 px-1 shadow-none focus-visible:ring-0 min-w-[8ch]"
+      />
+    </div>
+  );
+}

package/src/widgets/deriveLookupColumns.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { deriveLookupColumns } from './deriveLookupColumns';
+
+const accountSchema = {
+  name: 'showcase_account',
+  fields: {
+    created_at: { type: 'datetime', label: 'Created At' },
+    updated_at: { type: 'datetime', label: 'Last Modified At' },
+    name: { type: 'text', label: 'Account Name' },
+    industry: { type: 'select', label: 'Industry' },
+    annual_revenue: { type: 'currency', label: 'Annual Revenue' },
+    website: { type: 'url', label: 'Website' },
+    hq: { type: 'location', label: 'Headquarters' },
+    status: { type: 'select', label: 'Lifecycle' },
+    support_config: { type: 'json', label: 'Support Config' },
+    owner_id: { type: 'lookup', label: 'Owner' },
+    organization_id: { type: 'lookup', label: 'Organization' },
+  },
+};
+
+describe('deriveLookupColumns', () => {
+  it('returns [] when no schema/fields are available', () => {
+    expect(deriveLookupColumns(undefined, { displayField: 'name' })).toEqual([]);
+    expect(deriveLookupColumns({ fields: {} }, { displayField: 'name' })).toEqual([]);
+  });
+
+  it('leads with the display field and adds business fields in declaration order', () => {
+    const cols = deriveLookupColumns(accountSchema, { displayField: 'name', max: 4 });
+    expect(cols.map((c) => c.field)).toEqual(['name', 'industry', 'annual_revenue', 'website']);
+  });
+
+  it('carries field label and type onto each column for type-aware rendering', () => {
+    const cols = deriveLookupColumns(accountSchema, { displayField: 'name', max: 3 });
+    expect(cols[0]).toEqual({ field: 'name', label: 'Account Name', type: 'text' });
+    expect(cols[2]).toEqual({ field: 'annual_revenue', label: 'Annual Revenue', type: 'currency' });
+  });
+
+  it('skips system/audit fields and heavy non-tabular types', () => {
+    const cols = deriveLookupColumns(accountSchema, { displayField: 'name', max: 10 });
+    const names = cols.map((c) => c.field);
+    expect(names).not.toContain('created_at');
+    expect(names).not.toContain('updated_at');
+    expect(names).not.toContain('owner_id');
+    expect(names).not.toContain('organization_id');
+    expect(names).not.toContain('support_config'); // json
+    expect(names).not.toContain('hq'); // location
+  });
+
+  it('respects the max column cap', () => {
+    expect(deriveLookupColumns(accountSchema, { displayField: 'name', max: 2 })).toHaveLength(2);
+  });
+
+  it('honours an object-level displayFields list, with the display field first', () => {
+    const schema = {
+      fields: {
+        name: { type: 'text', label: 'Name' },
+        code: { type: 'text', label: 'Code' },
+        region: { type: 'select', label: 'Region' },
+      },
+      displayFields: ['code', 'region'],
+    };
+    const cols = deriveLookupColumns(schema, { displayField: 'name', max: 4 });
+    expect(cols.map((c) => c.field)).toEqual(['name', 'code', 'region']);
+  });
+
+  it('does not duplicate the display field when it also appears in displayFields', () => {
+    const schema = {
+      fields: { name: { type: 'text' }, region: { type: 'select' } },
+      displayFields: ['name', 'region'],
+    };
+    const cols = deriveLookupColumns(schema, { displayField: 'name' });
+    expect(cols.map((c) => c.field)).toEqual(['name', 'region']);
+  });
+});

package/src/widgets/deriveLookupColumns.ts

@@ -0,0 +1,104 @@
+import type { LookupColumnDef } from '@object-ui/types';
+
+/**
+ * System / audit fields that carry no disambiguating value in a record picker.
+ * Excluded from auto-derived columns so the picker shows business data, not
+ * bookkeeping.
+ */
+const SYSTEM_FIELDS = new Set<string>([
+  'id', '_id',
+  'created', 'modified', 'created_at', 'updated_at',
+  'created_by', 'updated_by', 'modified_by',
+  'owner_id', 'organization_id', 'space', 'company_id',
+  'instance_state', 'locked', 'is_deleted', 'deleted',
+]);
+
+/**
+ * Field types that don't render usefully as a compact picker column (large
+ * blobs, media, geometry, free-form text). Kept out of auto-derived columns.
+ */
+const NON_TABULAR_TYPES = new Set<string>([
+  'json', 'object', 'grid', 'html', 'richtext', 'markdown', 'code',
+  'image', 'file', 'avatar', 'vector', 'location', 'geometry',
+  'textarea', 'secret', 'password', 'encrypted',
+]);
+
+export interface DeriveColumnsOptions {
+  /** Primary display field — always the leading column. */
+  displayField: string;
+  /** Maximum number of columns to derive (including the display field). */
+  max?: number;
+}
+
+interface ObjectSchemaLike {
+  fields?: Record<string, { type?: string; label?: string; hidden?: boolean }>;
+  /** Object-level "fields to display in search result cards" (spec metadata). */
+  displayFields?: unknown;
+}
+
+function dedupe(names: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const n of names) {
+    if (!seen.has(n)) {
+      seen.add(n);
+      out.push(n);
+    }
+  }
+  return out;
+}
+
+/**
+ * Derive sensible Record Picker columns from a referenced object's schema when
+ * a lookup field declares no explicit `lookup_columns`.
+ *
+ * Priority:
+ *   1. The referenced object's own `displayFields` ("fields to display in
+ *      search result cards") — the author's declared search-card shape.
+ *   2. Otherwise the display field plus the next few business fields in
+ *      declaration order, skipping system/audit fields and heavy non-tabular
+ *      types.
+ *
+ * The result gives every lookup a multi-column, disambiguating picker with zero
+ * field-level configuration. Column `type` is carried through so the picker can
+ * render currency / select / date cells via the shared cell renderer.
+ *
+ * Returns an empty array when no usable schema is available, in which case the
+ * caller should fall back to the single display-field column.
+ */
+export function deriveLookupColumns(
+  objectSchema: ObjectSchemaLike | null | undefined,
+  { displayField, max = 4 }: DeriveColumnsOptions,
+): LookupColumnDef[] {
+  const fields = objectSchema?.fields ?? {};
+  const fieldDef = (name: string) => fields[name] ?? {};
+  const toCol = (name: string): LookupColumnDef => {
+    const f = fieldDef(name);
+    return { field: name, ...(f.label ? { label: f.label } : {}), ...(f.type ? { type: f.type } : {}) };
+  };
+
+  if (Object.keys(fields).length === 0) return [];
+
+  // 1. Honour the object's explicit search-card fields when present.
+  const declared = objectSchema?.displayFields;
+  if (Array.isArray(declared) && declared.length > 0) {
+    const names = (declared as unknown[]).filter(
+      (n): n is string => typeof n === 'string' && n.length > 0,
+    );
+    const ordered = dedupe([displayField, ...names.filter((n) => n !== displayField)]);
+    return ordered.slice(0, max).map(toCol);
+  }
+
+  // 2. Derive from the field set in declaration order.
+  const candidates = Object.keys(fields).filter((name) => {
+    if (name === displayField) return false;
+    if (SYSTEM_FIELDS.has(name)) return false;
+    const f = fieldDef(name);
+    if (f.hidden) return false;
+    if (f.type && NON_TABULAR_TYPES.has(f.type)) return false;
+    return true;
+  });
+
+  const ordered = dedupe([displayField, ...candidates]);
+  return ordered.slice(0, max).map(toCol);
+}

package/src/widgets/recentLookups.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { getRecentLookupIds, pushRecentLookupId } from './recentLookups';
+
+describe('recentLookups', () => {
+  beforeEach(() => localStorage.clear());
+
+  it('returns [] when nothing stored', () => {
+    expect(getRecentLookupIds('acc')).toEqual([]);
+  });
+
+  it('stores and returns ids most-recent-first', () => {
+    pushRecentLookupId('acc', 'a');
+    pushRecentLookupId('acc', 'b');
+    expect(getRecentLookupIds('acc')).toEqual(['b', 'a']);
+  });
+
+  it('de-dupes and moves a re-picked id to the front', () => {
+    pushRecentLookupId('acc', 'a');
+    pushRecentLookupId('acc', 'b');
+    pushRecentLookupId('acc', 'a');
+    expect(getRecentLookupIds('acc')).toEqual(['a', 'b']);
+  });
+
+  it('caps at 5 entries', () => {
+    for (const id of ['a', 'b', 'c', 'd', 'e', 'f', 'g']) pushRecentLookupId('acc', id);
+    const ids = getRecentLookupIds('acc');
+    expect(ids).toHaveLength(5);
+    expect(ids[0]).toBe('g');
+    expect(ids).not.toContain('a');
+  });
+
+  it('scopes per object name', () => {
+    pushRecentLookupId('acc', 'a');
+    pushRecentLookupId('prod', 'x');
+    expect(getRecentLookupIds('acc')).toEqual(['a']);
+    expect(getRecentLookupIds('prod')).toEqual(['x']);
+  });
+
+  it('ignores empty/nullish ids and object names', () => {
+    pushRecentLookupId('acc', '');
+    pushRecentLookupId('acc', null);
+    pushRecentLookupId('', 'a');
+    expect(getRecentLookupIds('acc')).toEqual([]);
+  });
+});