@object-ui/fields 11.3.0 → 11.5.0

package/src/widgets/LookupField.tsx

@@ -3,6 +3,9 @@ import { cn,
   Button,
   Input,
   Badge,
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
   Popover,
   PopoverTrigger,
   PopoverContent, EmptyValue } from '@object-ui/components';
@@ -11,11 +14,14 @@ import { FieldWidgetProps } from './types';
 import type { DataSource, QueryParams, LookupColumnDef } from '@object-ui/types';
 import { RecordPickerDialog, lookupFiltersToRecord } from './RecordPickerDialog';
 import type { RecordPickerFilterColumn } from './RecordPickerDialog';
+import { PeoplePicker } from './PeoplePicker';
+import { useRecordQuery } from './useRecordQuery';
 import { deriveLookupColumns } from './deriveLookupColumns';
 import { getRecordDisplayName } from '@object-ui/core';
 import { getRecentLookupIds, pushRecentLookupId } from './recentLookups';
+import { getPersonInitials } from './personDisplay';
 import { getCellRendererResolver } from './_cell-renderer-bridge';
-import { SchemaRendererContext as ImportedSchemaRendererContext } from '@object-ui/react';
+import { SchemaRendererContext as ImportedSchemaRendererContext, useAction, useHasActionProvider } from '@object-ui/react';
 import { useFieldTranslation } from './useFieldTranslation';
 
 export interface LookupOption {
@@ -34,6 +40,22 @@ const LOOKUP_PAGE_SIZE = 50;
  */
 const SchemaRendererContext: React.Context<any> = ImportedSchemaRendererContext;
 
+/**
+ * A relation whose picker should offer inline "create the referenced record" by
+ * default. Inline quick-create is a STANDARD capability so a freshly-built app
+ * isn't a dead end (an empty required picker → you can create the FIRST related
+ * record right here). Platform/system objects are excluded: the user directory
+ * (`sys_user` and its bare `user`/`users` aliases) and everything under the
+ * `sys_`/`cloud_`/`ai_` namespaces are pre-populated plumbing you must not create
+ * from a field picker. A user-authored business entity (customer, pet, book, …)
+ * never matches, so it gets the capability.
+ */
+const SYSTEM_REFERENCE_RX = /^(sys_|cloud_|ai_)/;
+const USER_DIRECTORY_REFS = new Set(['user', 'users']);
+function isUserFacingReference(reference: string | undefined): boolean {
+  return !!reference && !SYSTEM_REFERENCE_RX.test(reference) && !USER_DIRECTORY_REFS.has(reference);
+}
+
 /**
  * Render a record title from a `titleFormat` template (e.g. `{full_name}` or
  * `{case_number} - {subject}`). When a templated key resolves to an empty
@@ -90,7 +112,7 @@ function recordToOption(
   titleFormat?: string | null,
   objectDef?: any,
 ): LookupOption {
-  const val = record[idField] ?? record.id ?? record._id;
+  const val = record[idField] ?? record.id ?? record._id ?? record.externalId;
   const templated = titleFormat ? formatRecordTitle(record, titleFormat) : null;
 
   // Object-level resolver fallback (displayNameField + derivation), excluding
@@ -114,11 +136,31 @@ function recordToOption(
     record.full_name ??
     record.title ??
     record.subject ??
+    record.externalId ??
     String(val);
   const description = descriptionField ? record[descriptionField] : undefined;
   return { value: val, label: String(label), description, ...record };
 }
 
+/**
+ * A reference value can arrive JSON-encoded — e.g. an unresolved external-id
+ * reference `'{"externalId":"Website Relaunch"}'`. Parse such a string into its
+ * object form so the inline editor resolves it through the same path as a
+ * server-`$expand`ed record. Returns null for anything that isn't a JSON object
+ * string. Mirrors the read cell (`LookupCellRenderer`) so the two stay aligned.
+ */
+function parseReferenceObjectString(v: any): Record<string, any> | null {
+  if (typeof v !== 'string') return null;
+  const s = v.trim();
+  if (!s.startsWith('{') || !s.endsWith('}')) return null;
+  try {
+    const parsed = JSON.parse(s);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Map a LookupColumnDef.type to a filter input type for the filter bar.
  * Returns undefined if the field type is not filterable.
@@ -151,16 +193,12 @@ function mapFieldTypeToFilterType(
  */
 export function LookupField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
   const [isOpen, setIsOpen] = useState(false);
-  const [searchQuery, setSearchQuery] = useState('');
   const { t } = useFieldTranslation();
   const listboxId = React.useId();
 
-  // Dynamic data loading state
-  const [fetchedOptions, setFetchedOptions] = useState<LookupOption[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [totalCount, setTotalCount] = useState(0);
-  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Create-new error is local; the popover's fetch state (search/loading/error/
+  // total/options) is sourced from the shared useRecordQuery kernel below.
+  const [createError, setCreateError] = useState<string | null>(null);
 
   // Records selected via RecordPickerDialog (Level 2).
   // Stored as LookupOption so that findOption can resolve display labels
@@ -190,15 +228,28 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   const idField = fieldMeta?.id_field || 'id';
   // ObjectStack convention uses `reference`; types define `reference_to` — support both
   const referenceTo: string | undefined = fieldMeta?.reference_to || fieldMeta?.reference;
-  // Opt-in inline quick-create: when set, an empty/zero-result picker offers to
-  // create a record from the typed text via dataSource.create.
-  const allowCreate: boolean = !!(fieldMeta?.allow_create ?? fieldMeta?.allowCreate);
+  // Inline quick-create — a STANDARD capability, default ON for user-facing
+  // relations: an empty/zero-result picker offers to create the referenced
+  // record (opening its create form; see handleCreateNew) so the first related
+  // record can be made right here. An explicit `allowCreate` (either casing)
+  // wins — set it `false` to opt a field out; system/user-directory references
+  // are excluded from the default (isUserFacingReference).
+  const explicitAllowCreate = fieldMeta?.allow_create ?? fieldMeta?.allowCreate;
+  const allowCreate: boolean =
+    explicitAllowCreate != null ? !!explicitAllowCreate : isUserFacingReference(referenceTo);
 
   // Enterprise Record Picker configuration
   const lookupColumns: Array<string | LookupColumnDef> | undefined = fieldMeta?.lookup_columns ?? fieldMeta?.lookupColumns;
   const lookupPageSize: number | undefined = fieldMeta?.lookup_page_size ?? fieldMeta?.lookupPageSize;
   const lookupFilters: import('@object-ui/types').LookupFilterDef[] | undefined = fieldMeta?.lookup_filters ?? fieldMeta?.lookupFilters;
 
+  // Search-first PeoplePicker opt-in (user fields). When `picker === 'search'`
+  // the Level-2 picker is the rich PeoplePicker (avatar rows + selection tray)
+  // instead of the classic table dialog. `subtitle`/`avatar_field` drive the rows.
+  const pickerVariant: string | undefined = fieldMeta?.picker;
+  const subtitleFields: string[] | undefined = fieldMeta?.subtitle;
+  const avatarField: string = fieldMeta?.avatar_field ?? fieldMeta?.avatarField ?? 'image';
+
   /**
    * Dependent lookups — restrict candidates based on values of *other* fields
    * in the same form. Two shapes are accepted:
@@ -317,7 +368,54 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   // State for the full Record Picker dialog (Level 2)
   const [isPickerOpen, setIsPickerOpen] = useState(false);
 
+  // Dependent-lookup chain as a hard QueryParams.$filter record. Shared by
+  // EVERY candidate surface — quick-select popover, Level-2 table picker and
+  // the search-first PeoplePicker — so no picker can bypass the cascade
+  // (#2215: the table picker used to list the full unfiltered set).
+  const dependentFilter = useMemo<Record<string, any> | undefined>(() => {
+    const f: Record<string, any> = {};
+    for (const { field, param } of dependsOn) {
+      const v = resolvedDependentValues[field];
+      if (v === undefined || v === null || v === '') continue;
+      f[param] = typeof v === 'number' ? v : String(v);
+    }
+    return Object.keys(f).length > 0 ? f : undefined;
+  }, [dependsOn, resolvedDependentValues]);
+
   // Determine which options to display
+  // Quick-select popover fetch — the shared record-query kernel (same one the
+  // Record Picker dialog and PeoplePicker use). Filter = dependent-lookup chain
+  // + base lookupFilters, so the popover matches the full picker.
+  const popoverFilter = useMemo<Record<string, any> | undefined>(() => {
+    const f: Record<string, any> = {
+      ...(lookupFilters && lookupFilters.length > 0 ? lookupFiltersToRecord(lookupFilters) : {}),
+      ...(dependentFilter ?? {}),
+    };
+    return Object.keys(f).length > 0 ? f : undefined;
+  }, [dependentFilter, lookupFilters]);
+
+  const popoverQuery = useRecordQuery({
+    dataSource,
+    objectName: referenceTo,
+    enabled: isOpen && hasDataSource && !dependenciesMissing,
+    pageSize: LOOKUP_PAGE_SIZE,
+    filter: popoverFilter,
+  });
+
+  // Re-source the popover's fetch state from the kernel; all existing read sites
+  // (searchQuery / loading / error / totalCount / fetchedOptions) stay unchanged.
+  const searchQuery = popoverQuery.search;
+  const loading = popoverQuery.loading;
+  const totalCount = popoverQuery.total;
+  const error = popoverQuery.error ?? createError;
+  const fetchedOptions = useMemo(
+    () =>
+      popoverQuery.records.map(r =>
+        recordToOption(r, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema),
+      ),
+    [popoverQuery.records, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema],
+  );
+
   const allOptions = hasDataSource ? fetchedOptions : staticOptions;
 
   // For static options, filter locally based on search
@@ -336,124 +434,19 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
     setActiveIndex(-1);
   }, [filteredOptions.length]);
 
-  // Fetch data from DataSource
-  const fetchLookupData = useCallback(
-    async (search?: string) => {
-      if (!dataSource || !referenceTo) return;
-      // Don't issue a request that ignores configured dependencies.
-      if (dependenciesMissing) {
-        setFetchedOptions([]);
-        setTotalCount(0);
-        return;
-      }
-
-      setLoading(true);
-      setError(null);
-
-      try {
-        const params: QueryParams = {
-          $top: LOOKUP_PAGE_SIZE,
-        };
-        if (search && search.trim()) {
-          params.$search = search.trim();
-        }
-
-        // Build a dependent-lookup filter chain: AND of `param eq value`.
-        // QueryParams.$filter is a Record<string, any> — adapters convert to
-        // the underlying query language (OData, ObjectQL, etc).
-        if (dependsOn.length > 0) {
-          const filterEntries: Record<string, any> = {};
-          for (const { field, param } of dependsOn) {
-            const v = resolvedDependentValues[field];
-            if (v === undefined || v === null || v === '') continue;
-            filterEntries[param] = typeof v === 'number' ? v : String(v);
-          }
-          if (Object.keys(filterEntries).length > 0) {
-            params.$filter = filterEntries;
-          }
-        }
-
-        // Apply base scoping filters so the quick-select popover matches the
-        // full picker dialog (lookupFilters were previously dialog-only).
-        if (lookupFilters && lookupFilters.length > 0) {
-          params.$filter = { ...(params.$filter ?? {}), ...lookupFiltersToRecord(lookupFilters) };
-        }
-
-        const result = await dataSource.find(referenceTo, params);
-        const records: any[] = result?.data ?? result ?? [];
-        const mapped = records.map(r => recordToOption(r, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema));
-
-        setFetchedOptions(mapped);
-        setTotalCount(result?.total ?? records.length);
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        setError(msg);
-        setFetchedOptions([]);
-      } finally {
-        setLoading(false);
-      }
-    },
-    [dataSource, referenceTo, displayField, idField, effectiveDescriptionField, refTitleFormat, dependenciesMissing, dependsOn, resolvedDependentValues, lookupFilters],
-  );
-
-  // Re-fetch when dependent values change while the picker is open. This keeps
-  // a "City" dropdown reactive when the user changes "Country" without closing.
-  const dependencySignature = useMemo(
-    () => dependsOn.map(d => `${d.param}=${resolvedDependentValues[d.field] ?? ''}`).join('|'),
-    [dependsOn, resolvedDependentValues],
-  );
-  useEffect(() => {
-    if (isOpen && hasDataSource && dependsOn.length > 0) {
-      fetchLookupData(searchQuery || undefined);
-      // Clear local selection if it no longer satisfies the new filter chain —
-      // out of scope here; consumer should validate on submit.
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [dependencySignature]);
-
-  // Fetch data when dialog opens.
-  // We intentionally depend only on `isOpen` so the effect fires once per
-  // open/close transition. `fetchLookupData` is stable-enough via its own
-  // useCallback deps; including it here would cause spurious re-fetches.
+  // Reset the keyboard cursor when the popover closes. Fetch state (records,
+  // search, error, total) is owned by `popoverQuery` and resets automatically
+  // when it becomes disabled (via `enabled`), including its debounced search.
   useEffect(() => {
-    if (isOpen && hasDataSource) {
-      fetchLookupData(searchQuery || undefined);
-    }
-    // Clean up fetched data when dialog closes
-    if (!isOpen) {
-      setSearchQuery('');
-      setError(null);
-      setActiveIndex(-1);
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+    if (!isOpen) setActiveIndex(-1);
   }, [isOpen]);
 
-  // Debounced search
+  // Search is the kernel's debounced setter.
   const handleSearchChange = useCallback(
-    (query: string) => {
-      setSearchQuery(query);
-
-      if (!hasDataSource) return;
-
-      if (debounceTimer.current) {
-        clearTimeout(debounceTimer.current);
-      }
-      debounceTimer.current = setTimeout(() => {
-        fetchLookupData(query || undefined);
-      }, 300);
-    },
-    [hasDataSource, fetchLookupData],
+    (query: string) => popoverQuery.setSearch(query),
+    [popoverQuery.setSearch],
   );
 
-  // Clean up debounce timer
-  useEffect(() => {
-    return () => {
-      if (debounceTimer.current) {
-        clearTimeout(debounceTimer.current);
-      }
-    };
-  }, []);
-
   /**
    * Hydrate the picker's display when the field already has a value (e.g.
    * edit-mode load, prefill via query-string from a related-list "+ New")
@@ -463,9 +456,17 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
    */
   useEffect(() => {
     if (!hasDataSource || !dataSource || !referenceTo) return;
-    const ids: any[] = multiple
+    const raw: any[] = multiple
       ? Array.isArray(value) ? value : []
       : value != null && value !== '' ? [value] : [];
+    // Expanded-reference values (server `$expand`, or their JSON-encoded string
+    // form) already carry their display fields and resolve directly in
+    // `resolveSelectedOption` — only bare ids need a fetch. Passing an object (or
+    // a JSON string) to `findOne` would query for a bogus id and leave the
+    // trigger stuck on the placeholder.
+    const ids = raw.filter(
+      (v) => v != null && v !== '' && typeof v !== 'object' && !parseReferenceObjectString(v),
+    );
     if (!ids.length) return;
     // Only fetch records we haven't resolved yet.
     const unresolved = ids.filter((v) => !findOption(v));
@@ -517,9 +518,57 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
     [staticOptions, fetchedOptions, pickerResolvedRecords],
   );
 
+  // String-coerced fallback for `findOption` — matches the read cell's tolerant
+  // `String(a) === String(b)` comparison so a numeric cell value still resolves
+  // against a string-keyed option (and vice versa). Only consulted when the
+  // strict match misses, so homogeneous option lists are unaffected.
+  const findOptionLoose = useCallback(
+    (v: any): LookupOption | undefined => {
+      const key = String(v);
+      return (
+        staticOptions.find(opt => String(opt.value) === key) ??
+        fetchedOptions.find(opt => String(opt.value) === key) ??
+        pickerResolvedRecords.find(opt => String(opt.value) === key)
+      );
+    },
+    [staticOptions, fetchedOptions, pickerResolvedRecords],
+  );
+
+  // Collapse an expanded-reference value (the related record object returned by
+  // server `$expand`) to its bare id — used for option matching / highlighting.
+  const normalizeId = useCallback(
+    (raw: any): any => {
+      const obj = raw != null && typeof raw === 'object' ? raw : parseReferenceObjectString(raw);
+      return obj ? (obj[idField] ?? obj.id ?? obj._id ?? obj.externalId) : raw;
+    },
+    [idField],
+  );
+
+  // Resolve a raw field value into its display option. An expanded-reference
+  // object is mapped directly (mirroring the read cell's display-name path) so
+  // the inline editor shows the record's name instead of the placeholder; a bare
+  // id resolves through the static / fetched / picker-hydrated option lists.
+  const resolveSelectedOption = useCallback(
+    (raw: any): LookupOption | undefined => {
+      if (raw == null || raw === '') return undefined;
+      // An expanded-reference object (server `$expand`) — or its JSON-encoded
+      // string form, e.g. an external-id reference `'{"externalId":"…"}'` — is
+      // mapped directly, mirroring the read cell (`LookupCellRenderer`).
+      const asObject = typeof raw === 'object' ? raw : parseReferenceObjectString(raw);
+      if (asObject) {
+        return recordToOption(asObject, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema);
+      }
+      // Bare id: strict match first, then a String()-coerced fallback so a
+      // numeric cell value still resolves against a string-keyed option (and
+      // vice versa) — matching the read cell's tolerant comparison.
+      return findOption(raw) ?? findOptionLoose(raw);
+    },
+    [findOption, findOptionLoose, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema],
+  );
+
   const selectedOptions = multiple
-    ? (Array.isArray(value) ? value : []).map(findOption).filter(Boolean)
-    : value ? [findOption(value)].filter(Boolean) : [];
+    ? (Array.isArray(value) ? value : []).map(resolveSelectedOption).filter(Boolean)
+    : value ? [resolveSelectedOption(value)].filter(Boolean) : [];
 
   // Optional: receive the FULL selected record (not just its id) so a host can
   // auto-fill sibling fields from it — e.g. a line-item grid copying a product's
@@ -529,8 +578,22 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
 
   const handleSelect = useCallback(
     (option: LookupOption) => {
+      // Cache the picked option so its label resolves synchronously and durably,
+      // independent of the popover's `fetchedOptions` (which the editor may have
+      // remounted away, or which a slow/contended re-render hasn't surfaced yet —
+      // the intermittent CI failure where a just-picked lookup showed no label,
+      // #2150). `selectedOptions` consults `pickerResolvedRecords` in `findOption`.
+      if (option && option.value != null) {
+        setPickerResolvedRecords((prev) => {
+          const map = new Map(prev.map((o) => [o.value, o]));
+          map.set(option.value, option);
+          return Array.from(map.values());
+        });
+      }
       if (multiple) {
-        const currentValues = Array.isArray(value) ? value : [];
+        // Normalise any expanded-reference objects to bare ids so toggling
+        // compares like-for-like and always persists ids (never mixed shapes).
+        const currentValues = (Array.isArray(value) ? value : []).map(normalizeId);
         const isSelected = currentValues.includes(option.value);
 
         if (isSelected) {
@@ -546,12 +609,12 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
         setIsOpen(false);
       }
     },
-    [multiple, value, onChange, onSelectRecord, referenceTo],
+    [multiple, value, onChange, onSelectRecord, referenceTo, normalizeId],
   );
 
   const handleRemove = (optionValue: any) => {
     if (multiple) {
-      const currentValues = Array.isArray(value) ? value : [];
+      const currentValues = (Array.isArray(value) ? value : []).map(normalizeId);
       onChange(currentValues.filter((v: any) => v !== optionValue));
     } else {
       onChange(null);
@@ -605,26 +668,72 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   useEffect(() => { setActiveIndex(-1); }, [visibleOptions.length]);
 
   const [creating, setCreating] = useState(false);
-  const canCreate = !!onCreateNew || (allowCreate && hasDataSource);
+  // Open the referenced object's create form through the ActionProvider's modal
+  // handler (when a form host wired one). Safe outside a provider — useAction
+  // returns a local runner and useHasActionProvider is false.
+  const { execute } = useAction();
+  const hasActionProvider = useHasActionProvider();
+  const canCreate = !!onCreateNew || (allowCreate && (hasActionProvider || hasDataSource));
   const handleCreateNew = useCallback(
     async (q: string) => {
       const label = (q || '').trim();
       if (onCreateNew) { onCreateNew(label); setIsOpen(false); return; }
-      if (!allowCreate || !dataSource || !referenceTo || !label) return;
+      if (!allowCreate || !referenceTo) return;
+      setCreateError(null);
+
+      // Preferred path — open the referenced object's FULL create form so the
+      // user fills every required field themselves, then select the record they
+      // created. This is the standard "create related record" behaviour: it
+      // works for ANY object (not only ones whose sole required field is the
+      // title) and turns an empty required picker from a dead end into a way to
+      // author the first related record.
+      if (hasActionProvider) {
+        setIsOpen(false); // close the picker popover first
+        // Defer opening the create dialog until the popover has fully closed and
+        // returned focus to the field trigger. Two nested-modal bugs come from
+        // opening it in the same tick as the triggering click:
+        //  1) the just-mounted Dialog treats this click's release (and the
+        //     popover's own dismiss) as an outside-interaction and flashes shut
+        //     on the FIRST click (works on the second);
+        //  2) with the popover already gone, the "+ create" button that Radix
+        //     would return focus to is unmounted, so when the nested modal later
+        //     closes focus leaks to <body> and dismisses the PARENT form's dialog
+        //     too ("Cancel closes both").
+        // A macrotask runs after Radix's focus-return layout effects, so focus is
+        // safely back on the still-mounted field trigger before the Dialog opens.
+        await new Promise((r) => setTimeout(r, 0));
+        const result: any = await execute({
+          type: 'modal',
+          modal: { objectName: referenceTo, mode: 'create' },
+        } as any);
+        if (result?.success && result.data) {
+          const opt = recordToOption(result.data, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema);
+          setPickerResolvedRecords((prev) => [opt, ...prev.filter((o) => o.value !== opt.value)]);
+          handleSelect(opt);
+          return;
+        }
+        // `success` + an echoed `modal` schema means no modal handler was wired
+        // in this tree → fall through to the legacy inline create. Anything else
+        // (cancel / no data) means the user backed out → stop.
+        if (!(result?.success && result.modal)) return;
+      }
+
+      // Fallback (no modal handler in scope): the legacy one-field inline create
+      // from the typed text. Best-effort; surfaces any validation error inline.
+      if (!dataSource || !label) return;
       setCreating(true);
-      setError(null);
       try {
         const created = await (dataSource as any).create(referenceTo, { [displayField]: label });
         const opt = recordToOption(created, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema);
         setPickerResolvedRecords((prev) => [opt, ...prev.filter((o) => o.value !== opt.value)]);
         handleSelect(opt);
       } catch (err) {
-        setError(err instanceof Error ? err.message : String(err));
+        setCreateError(err instanceof Error ? err.message : String(err));
       } finally {
         setCreating(false);
       }
     },
-    [onCreateNew, allowCreate, dataSource, referenceTo, displayField, idField, effectiveDescriptionField, refTitleFormat, handleSelect],
+    [onCreateNew, allowCreate, referenceTo, hasActionProvider, execute, dataSource, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema, handleSelect],
   );
 
   // Compact one-line preview of an option's extra (non-display) columns —
@@ -706,63 +815,121 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   const compact = !!(props as any).compact;
   const singleSelectedLabel = selectedOptions[0]?.label || selectedOptions[0]?.[displayField];
 
+  // Shared field trigger — the anchor for either the inline PeoplePicker
+  // (search fields) or the classic quick-select popover. No onClick: the Radix
+  // trigger it is slotted into (PopoverTrigger / SheetTrigger) owns open/close.
+  const triggerButton = (
+    <Button
+      variant="outline"
+      className={cn(
+        'min-w-0 flex-1 justify-start text-left font-normal',
+        compact && 'h-8 rounded-none border-0 bg-transparent px-2 shadow-none focus-visible:ring-1 focus-visible:ring-ring/60',
+      )}
+      type="button"
+      disabled={dependenciesMissing || (props as any).disabled}
+      data-testid={dependenciesMissing ? 'lookup-trigger-gated' : (((props as any).name || lookupField?.name) ? `lookup-trigger-${(props as any).name || lookupField.name}` : 'lookup-trigger')}
+      title={dependenciesMissing
+        ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
+        : undefined}
+    >
+      <Search className={cn('size-4 shrink-0 text-muted-foreground', compact ? 'mr-1.5' : 'mr-2')} />
+      <span className={cn('truncate', compact && selectedOptions.length === 0 && 'text-muted-foreground')}>
+        {dependenciesMissing
+          ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
+          : compact && !multiple && selectedOptions.length > 0
+            ? singleSelectedLabel
+            : selectedOptions.length === 0
+              ? lookupField?.placeholder || t('common.select')
+              : multiple ? t('table.selected', { count: selectedOptions.length }) : t('common.select')}
+      </span>
+    </Button>
+  );
+
   return (
     <div className={compact ? '' : 'space-y-2'}>
       {/* Selected values display (full mode only — compact shows it in-trigger) */}
       {selectedOptions.length > 0 && !compact && (
         <div className="flex flex-wrap gap-1">
-          {selectedOptions.map((opt, idx) => (
-            <Badge
-              key={idx}
-              variant="outline"
-              className="gap-1"
-            >
-              {opt?.label || opt?.[displayField]}
-              <button
-                onClick={() => handleRemove(opt?.value)}
-                className="ml-1 hover:text-destructive"
-                type="button"
-                aria-label={t('lookup.remove', { label: opt?.label || opt?.[displayField] })}
-              >
-                <X className="size-3" />
-              </button>
-            </Badge>
-          ))}
+          {selectedOptions.map((opt, idx) => {
+            const chipLabel = opt?.label || opt?.[displayField];
+            // Search-first (people) fields show avatar chips; classic lookups
+            // keep the plain text Badge.
+            if (pickerVariant === 'search') {
+              const avatarUrl = (opt as any)?.[avatarField] || (opt as any)?.image;
+              return (
+                <span
+                  key={idx}
+                  data-testid="people-field-chip"
+                  className="inline-flex items-center gap-1.5 rounded-full border bg-background py-0.5 pl-0.5 pr-1.5 text-sm"
+                >
+                  <Avatar className="size-6 shrink-0">
+                    {avatarUrl && <AvatarImage src={avatarUrl} alt={String(chipLabel || '')} />}
+                    <AvatarFallback className="text-[10px]">
+                      {getPersonInitials(String(chipLabel || ''))}
+                    </AvatarFallback>
+                  </Avatar>
+                  <span className="max-w-[10rem] truncate">{chipLabel}</span>
+                  <button
+                    onClick={() => handleRemove(opt?.value)}
+                    className="rounded-full p-0.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+                    type="button"
+                    aria-label={t('lookup.remove', { label: chipLabel })}
+                  >
+                    <X className="size-3" />
+                  </button>
+                </span>
+              );
+            }
+            return (
+              <Badge key={idx} variant="outline" className="gap-1">
+                {chipLabel}
+                <button
+                  onClick={() => handleRemove(opt?.value)}
+                  className="ml-1 hover:text-destructive"
+                  type="button"
+                  aria-label={t('lookup.remove', { label: chipLabel })}
+                >
+                  <X className="size-3" />
+                </button>
+              </Badge>
+            );
+          })}
         </div>
       )}
 
-      {/* Level 1: Quick-select Popover (inline typeahead) */}
+      {/* Field control: search-first inline combobox (anchored dropdown / mobile
+          sheet), else the classic quick-select popover. */}
+      {pickerVariant === 'search' && hasDataSource && dataSource && referenceTo ? (
+        <PeoplePicker
+          inline
+          trigger={triggerButton}
+          open={isPickerOpen}
+          onOpenChange={setIsPickerOpen}
+          title={lookupField?.label || t('common.select')}
+          multiple={multiple}
+          dataSource={dataSource}
+          objectName={referenceTo}
+          displayField={displayField}
+          idField={idField}
+          subtitleFields={subtitleFields}
+          avatarField={avatarField}
+          pageSize={lookupPageSize}
+          value={value}
+          onSelect={onChange}
+          onSelectRecords={handlePickerSelectRecords}
+          lookupFilters={lookupFilters}
+          baseFilter={dependentFilter}
+        />
+      ) : (
       <div className="flex items-center gap-1.5">
-      <Popover open={isOpen} onOpenChange={(o) => !dependenciesMissing && setIsOpen(o)}>
+      <Popover
+        open={isOpen}
+        onOpenChange={(o) => {
+          if (!dependenciesMissing) setIsOpen(o);
+        }}
+      >
         <PopoverTrigger asChild>
-          <Button
-            variant="outline"
-            className={cn(
-              'min-w-0 flex-1 justify-start text-left font-normal',
-              compact && 'h-8 rounded-none border-0 bg-transparent px-2 shadow-none focus-visible:ring-1 focus-visible:ring-ring/60',
-            )}
-            type="button"
-            aria-haspopup="listbox"
-            aria-expanded={isOpen}
-            aria-controls={listboxId}
-            disabled={dependenciesMissing || (props as any).disabled}
-            data-testid={dependenciesMissing ? 'lookup-trigger-gated' : (((props as any).name || lookupField?.name) ? `lookup-trigger-${(props as any).name || lookupField.name}` : 'lookup-trigger')}
-            title={dependenciesMissing
-              ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
-              : undefined}
-          >
-            <Search className={cn('size-4 shrink-0 text-muted-foreground', compact ? 'mr-1.5' : 'mr-2')} />
-            <span className={cn('truncate', compact && selectedOptions.length === 0 && 'text-muted-foreground')}>
-            {dependenciesMissing
-              ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
-              : compact && !multiple && selectedOptions.length > 0
-                ? singleSelectedLabel
-                : selectedOptions.length === 0
-                  ? lookupField?.placeholder || t('common.select')
-                  : multiple ? t('table.selected', { count: selectedOptions.length }) : t('common.select')
-            }
-            </span>
-          </Button>
+          {triggerButton}
         </PopoverTrigger>
         <PopoverContent className="w-[var(--radix-popover-trigger-width)] p-0" align="start">
           {/* Search input */}
@@ -798,7 +965,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
               <Button
                 variant="outline"
                 size="sm"
-                onClick={() => fetchLookupData(searchQuery || undefined)}
+                onClick={() => popoverQuery.refetch()}
                 type="button"
               >
                 {t('lookup.retry')}
@@ -841,8 +1008,8 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
                 <>
                   {visibleOptions.map((option, idx) => {
                     const isSelected = multiple
-                      ? (Array.isArray(value) ? value : []).includes(option.value)
-                      : value === option.value;
+                      ? (Array.isArray(value) ? value : []).map(normalizeId).includes(option.value)
+                      : normalizeId(value) === option.value;
                     const isActive = idx === activeIndex;
                     const showRecentHeader = recentCount > 0 && idx === 0;
                     const showResultsHeader = recentCount > 0 && idx === recentCount;
@@ -930,25 +1097,32 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
         </PopoverContent>
       </Popover>
 
-      {/* "Browse All" button — always visible when DataSource is available */}
-      {hasDataSource && (
+      {/* "Browse All" button — classic lookups only; search fields open the
+          PeoplePicker from the trigger itself, so this would be redundant. */}
+      {hasDataSource && pickerVariant !== 'search' && (
         <Button
           variant="outline"
           size="icon"
           className="shrink-0"
           type="button"
+          // Gated exactly like the main trigger (#2215) — pre-fix this button
+          // opened the full unscoped table while the dependency was missing.
+          disabled={dependenciesMissing || (props as any).disabled}
           onClick={() => setIsPickerOpen(true)}
           aria-label={t('lookup.browseAll')}
-          title={t('lookup.browseAll')}
+          title={dependenciesMissing
+            ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
+            : t('lookup.browseAll')}
           data-testid="browse-all-records"
         >
           <TableProperties className="size-4" />
         </Button>
       )}
       </div>
+      )}
 
-      {/* Level 2: Full Record Picker Dialog */}
-      {hasDataSource && dataSource && referenceTo && (
+      {/* Level 2: classic table picker — search fields use the inline combobox above. */}
+      {hasDataSource && dataSource && referenceTo && pickerVariant !== 'search' && (
         <RecordPickerDialog
           open={isPickerOpen}
           onOpenChange={setIsPickerOpen}
@@ -965,6 +1139,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
           onSelect={onChange}
           onSelectRecords={handlePickerSelectRecords}
           lookupFilters={lookupFilters}
+          baseFilter={dependentFilter}
           cellRenderer={getCellRendererResolver()}
           filterColumns={filterColumns}
         />