@object-ui/fields 16.1.0 → 17.1.0

package/src/widgets/LookupField.hydration.test.tsx

@@ -0,0 +1,136 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Regression (#3108): a multi-value lookup hydrated its committed ids with a
+ * SERIAL `findOne` per id — 41 selected users meant 41 sequential round-trips,
+ * during which the trigger rendered the bare "Select…" placeholder,
+ * indistinguishable from having no value at all.
+ *
+ * Fixed behaviour under test:
+ *  1. unresolved ids are fetched in ONE batched `$in` query (chunked), not
+ *     one findOne per id;
+ *  2. while hydration is in flight the trigger shows a loading indicator and
+ *     the committed-value count instead of the empty placeholder;
+ *  3. the loading state settles (falls back to placeholder) when hydration
+ *     fails, instead of spinning forever.
+ */
+
+import * as React from 'react';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup, waitFor, screen } from '@testing-library/react';
+import { LookupField } from './LookupField';
+
+afterEach(cleanup);
+
+const USERS = [
+  { id: 'u1', name: 'Ada Lovelace' },
+  { id: 'u2', name: 'Grace Hopper' },
+  { id: 'u3', name: 'Margaret Hamilton' },
+];
+
+describe('LookupField — multi-value hydration batches and shows loading (#3108)', () => {
+  it('hydrates several ids with one $in query instead of a findOne per id', async () => {
+    const find = vi.fn(async (_obj: string, params: any) => {
+      const wanted: any[] = params?.$filter?.id?.$in ?? [];
+      return { data: USERS.filter((u) => wanted.includes(u.id)) };
+    });
+    const findOne = vi.fn(async () => null);
+    render(
+      <LookupField
+        value={['u1', 'u2', 'u3']}
+        onChange={() => {}}
+        dataSource={{ find, findOne } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+
+    await waitFor(() => expect(screen.getByText('Ada Lovelace')).toBeTruthy());
+    expect(screen.getByText('Grace Hopper')).toBeTruthy();
+    expect(screen.getByText('Margaret Hamilton')).toBeTruthy();
+
+    // One batched round-trip, zero per-id GETs.
+    expect(findOne).not.toHaveBeenCalled();
+    const hydrationCalls = find.mock.calls.filter((c) => c[1]?.$filter?.id?.$in);
+    expect(hydrationCalls).toHaveLength(1);
+    expect(hydrationCalls[0][1].$filter.id.$in).toEqual(['u1', 'u2', 'u3']);
+  });
+
+  it('shows the committed count + spinner while hydration is in flight, never the empty placeholder', async () => {
+    let resolveFind!: (v: any) => void;
+    const find = vi.fn(
+      () => new Promise((resolve) => { resolveFind = resolve; }),
+    );
+    render(
+      <LookupField
+        value={['u1', 'u2', 'u3']}
+        onChange={() => {}}
+        dataSource={{ find } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+
+    // In-flight: loading indicator + raw committed count, no "Select…".
+    await waitFor(() => expect(screen.getByTestId('lookup-hydrating')).toBeTruthy());
+    expect(screen.queryByText('Select...')).toBeNull();
+    expect(screen.getByText(/3/)).toBeTruthy();
+
+    resolveFind({ data: USERS });
+    await waitFor(() => expect(screen.getByText('Ada Lovelace')).toBeTruthy());
+    expect(screen.queryByTestId('lookup-hydrating')).toBeNull();
+  });
+
+  it('settles (no infinite spinner) when the hydration fetch fails', async () => {
+    const find = vi.fn(async (_obj: string, params: any) => {
+      if (params?.$filter?.id?.$in) throw new Error('boom');
+      return { data: [] };
+    });
+    render(
+      <LookupField
+        value={['u1', 'u2']}
+        onChange={() => {}}
+        dataSource={{ find } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+
+    await waitFor(() => expect(find).toHaveBeenCalled());
+    // The failed attempt is marked settled — the spinner clears instead of
+    // spinning forever (pre-existing fallback: unresolvable ids drop).
+    await waitFor(() => expect(screen.queryByTestId('lookup-hydrating')).toBeNull());
+  });
+
+  it('readonly mode shows the loading count instead of an empty value while hydrating', async () => {
+    let resolveFind!: (v: any) => void;
+    const find = vi.fn(
+      () => new Promise((resolve) => { resolveFind = resolve; }),
+    );
+    render(
+      <LookupField
+        value={['u1', 'u2']}
+        onChange={() => {}}
+        readonly
+        dataSource={{ find } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+
+    await waitFor(() => expect(screen.getByTestId('lookup-hydrating')).toBeTruthy());
+
+    resolveFind({ data: USERS.slice(0, 2) });
+    await waitFor(() => expect(screen.getByText('Ada Lovelace')).toBeTruthy());
+  });
+
+  it('keeps the cheap findOne GET for a single unresolved primary id', async () => {
+    const find = vi.fn(async () => ({ data: [] }));
+    const findOne = vi.fn(async () => ({ id: 'u1', name: 'Ada' }));
+    render(
+      <LookupField
+        value={['u1']}
+        onChange={() => {}}
+        dataSource={{ find, findOne } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+    await waitFor(() => expect(findOne).toHaveBeenCalledWith('sys_user', 'u1'));
+  });
+});

package/src/widgets/LookupField.idField.test.tsx

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Regression (objectstack #3508): a lookup whose committed value is NOT the
+ * primary id (`id_field: 'name'` — e.g. approval `position` approvers, which
+ * the engine routes by machine name) must hydrate its display label by
+ * FILTERING on that field. The old path always called `findOne(object, value)`
+ * — a primary-id GET — so a stored machine name never resolved and the field
+ * showed an empty placeholder over a real value.
+ */
+
+import * as React from 'react';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup, waitFor } from '@testing-library/react';
+import { LookupField } from './LookupField';
+
+afterEach(cleanup);
+
+describe('LookupField — id_field hydration (#3508)', () => {
+  it('hydrates by filtering on id_field when it is not the primary id', async () => {
+    const find = vi.fn(async () => ({
+      data: [{ id: 'pos_1', name: 'sales_manager', label: 'Sales Manager' }],
+    }));
+    const findOne = vi.fn(async () => null);
+    render(
+      <LookupField
+        value="sales_manager"
+        onChange={() => {}}
+        dataSource={{ find, findOne } as never}
+        field={{
+          reference_to: 'sys_position',
+          id_field: 'name',
+          display_field: 'label',
+          multiple: false,
+        } as never}
+      />,
+    );
+    await waitFor(() => expect(find).toHaveBeenCalled());
+    // The stored machine name is not a primary id — findOne(object, name)
+    // would 404; hydration must go through $filter on the committed field.
+    expect(findOne).not.toHaveBeenCalled();
+    const hydration = find.mock.calls.find(
+      (c) => (c as unknown[])[1] && ((c as never[])[1] as { $filter?: Record<string, unknown> }).$filter?.name === 'sales_manager',
+    );
+    expect(hydration).toBeTruthy();
+  });
+
+  it('keeps findOne hydration for the default primary-id lookup', async () => {
+    const find = vi.fn(async () => ({ data: [] }));
+    const findOne = vi.fn(async () => ({ id: 'u1', name: 'Ada' }));
+    render(
+      <LookupField
+        value="u1"
+        onChange={() => {}}
+        dataSource={{ find, findOne } as never}
+        field={{ reference_to: 'sys_user', multiple: false } as never}
+      />,
+    );
+    await waitFor(() => expect(findOne).toHaveBeenCalledWith('sys_user', 'u1'));
+  });
+});

package/src/widgets/LookupField.tsx

@@ -205,6 +205,12 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   // even when the record wasn't part of the Level 1 popover fetch.
   const [pickerResolvedRecords, setPickerResolvedRecords] = useState<LookupOption[]>([]);
 
+  // Ids whose hydration attempt has FINISHED — found or not — keyed by
+  // String(id). Distinguishes "still loading" from "unresolvable" (deleted
+  // record, fetch failure) so the trigger's hydrating state can't stick
+  // forever on an id that will never resolve (#3108).
+  const [hydrationSettled, setHydrationSettled] = useState<Set<string>>(() => new Set());
+
   // Arrow-key active index (-1 = none)
   const [activeIndex, setActiveIndex] = useState(-1);
   const listRef = useRef<HTMLDivElement>(null);
@@ -476,8 +482,13 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
     (async () => {
       try {
         const fetched: LookupOption[] = [];
-        for (const id of unresolved) {
-          if (typeof (dataSource as any).findOne === 'function') {
+        // Single id: the pre-existing cheap paths — a primary-id `findOne`
+        // GET, or an equality filter when the field commits a different
+        // column (`id_field: 'name'` — e.g. position machine names,
+        // objectstack #3508).
+        if (unresolved.length === 1) {
+          const id = unresolved[0];
+          if (typeof (dataSource as any).findOne === 'function' && idField === 'id') {
             const rec = await (dataSource as any).findOne(referenceTo, id);
             if (rec) fetched.push(recordToOption(rec, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema));
           } else {
@@ -485,9 +496,35 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
               $filter: { [idField]: id },
               $top: 1,
             } as QueryParams);
-            const rows = res?.data ?? res ?? [];
+            const rows = (res as any)?.data ?? res ?? [];
             if (rows[0]) fetched.push(recordToOption(rows[0], displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema));
           }
+        } else {
+          // SEVERAL unresolved ids: one `$in` query per chunk. A multi-value
+          // field can hold dozens of ids, and the old serial findOne-per-id
+          // took seconds while the trigger sat on the empty "Select…"
+          // placeholder (#3108).
+          // Chunked to LOOKUP_PAGE_SIZE so no request exceeds the page size
+          // a server may cap `$top` at; chunks run in parallel.
+          const chunks: any[][] = [];
+          for (let i = 0; i < unresolved.length; i += LOOKUP_PAGE_SIZE) {
+            chunks.push(unresolved.slice(i, i + LOOKUP_PAGE_SIZE));
+          }
+          const results = await Promise.all(
+            chunks.map((chunk) =>
+              dataSource.find(referenceTo, {
+                $filter: { [idField]: { $in: chunk } },
+                $top: chunk.length,
+              } as QueryParams),
+            ),
+          );
+          for (const res of results) {
+            const rows = (res as any)?.data ?? res ?? [];
+            if (!Array.isArray(rows)) continue;
+            for (const row of rows) {
+              fetched.push(recordToOption(row, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema));
+            }
+          }
         }
         if (!cancelled && fetched.length) {
           setPickerResolvedRecords((prev) => {
@@ -498,6 +535,17 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
         }
       } catch {
         // Ignore — chip will fall back to showing the raw id.
+      } finally {
+        // Mark the attempt settled — found or not — so `hydrating` below
+        // clears even for ids that no longer resolve (deleted records,
+        // fetch failures) instead of spinning forever.
+        if (!cancelled) {
+          setHydrationSettled((prev) => {
+            const next = new Set(prev);
+            for (const id of unresolved) next.add(String(id));
+            return next;
+          });
+        }
       }
     })();
     return () => {
@@ -576,6 +624,31 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
     [findOption, findOptionLoose, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema],
   );
 
+  // A value can hold bare ids that no option list resolves YET — the batch
+  // hydration above is still in flight. While any such id is pending, the
+  // trigger must not present the field as empty: a 41-value lookup rendered
+  // the bare "Select…" placeholder for seconds, indistinguishable from
+  // having no value at all (#3108).
+  const hydrating = useMemo(() => {
+    if (!hasDataSource) return false;
+    const raw: any[] = multiple
+      ? Array.isArray(value) ? value : []
+      : value != null && value !== '' ? [value] : [];
+    return raw.some(
+      (v) =>
+        v != null && v !== '' && typeof v !== 'object' && !parseReferenceObjectString(v) &&
+        !findOption(v) && !findOptionLoose(v) &&
+        !hydrationSettled.has(String(v)),
+    );
+  }, [hasDataSource, multiple, value, findOption, findOptionLoose, hydrationSettled]);
+
+  // Committed-value count. During hydration the resolved-option count
+  // undercounts (unresolved ids are filtered out below), so the trigger
+  // shows this raw count instead.
+  const rawSelectedCount = multiple
+    ? (Array.isArray(value) ? value : []).filter((v) => v != null && v !== '').length
+    : value != null && value !== '' ? 1 : 0;
+
   const selectedOptions = multiple
     ? (Array.isArray(value) ? value : []).map(resolveSelectedOption).filter(Boolean)
     : value ? [resolveSelectedOption(value)].filter(Boolean) : [];
@@ -797,6 +870,17 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
 
   if (readonly) {
     if (!selectedOptions.length) {
+      if (hydrating) {
+        return (
+          <span
+            className="inline-flex items-center gap-1.5 text-sm text-muted-foreground"
+            data-testid="lookup-hydrating"
+          >
+            <Loader2 className="size-3.5 animate-spin" />
+            {multiple ? t('table.selected', { count: rawSelectedCount }) : t('lookup.loading')}
+          </span>
+        );
+      }
       return <EmptyValue />;
     }
 
@@ -842,15 +926,28 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
         ? 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')} />
+      {hydrating ? (
+        <Loader2
+          className={cn('size-4 shrink-0 animate-spin text-muted-foreground', compact ? 'mr-1.5' : 'mr-2')}
+          data-testid="lookup-hydrating"
+        />
+      ) : (
+        <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')}
+          : hydrating
+            // The value EXISTS but its labels are still loading — say so
+            // instead of the empty placeholder (#3108).
+            ? multiple
+              ? t('table.selected', { count: rawSelectedCount })
+              : t('lookup.loading')
+            : 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>
   );

package/src/widgets/MultiSelectField.tsx

@@ -98,12 +98,15 @@ export function MultiSelectField({
       data-testid={fieldName ? `multiselect-${fieldName}` : undefined}
     >
       {options.map((opt) => {
-        const active = selected.includes(opt.value);
+        // Multi-value fields store string arrays — stringify the (possibly
+        // numeric, #3090-widened) authored value at this boundary.
+        const value = String(opt.value);
+        const active = selected.includes(value);
         return (
           <button
             type="button"
-            key={opt.value}
-            onClick={() => toggle(opt.value)}
+            key={value}
+            onClick={() => toggle(value)}
             disabled={(props as any).disabled}
             aria-pressed={active}
             data-testid={`multiselect-option-${opt.value}`}

package/src/widgets/ObjectRefField.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { Combobox, EmptyValue, cn } from '@object-ui/components';
 import { SchemaRendererContext } from '@object-ui/react';
 import type { FieldWidgetProps } from './types';
+import { useFieldTranslation } from './useFieldTranslation';
 
 /**
  * ObjectRefField — object-name picker for form fields that store the machine
@@ -33,6 +34,7 @@ export function ObjectRefField({
   ...props
 }: FieldWidgetProps<string>) {
   const ctx = React.useContext(SchemaRendererContext);
+  const { t } = useFieldTranslation();
   const dataSource: any = (props as any).dataSource ?? (ctx as any)?.dataSource ?? null;
   const disabled = (props as any).disabled as boolean | undefined;
 
@@ -94,11 +96,14 @@ export function ObjectRefField({
       options={options}
       value={value ?? ''}
       onValueChange={(v) => onChange(v as any)}
-      placeholder={objects === null ? 'Loading objects…' : 'Select an object'}
-      searchPlaceholder="Search objects…"
-      emptyText={objects === null ? 'Loading…' : 'No objects found'}
+      placeholder={objects === null ? t('fields.objectRef.loading') : t('fields.objectRef.placeholder')}
+      searchPlaceholder={t('fields.objectRef.search')}
+      emptyText={objects === null ? t('common.loading') : t('fields.objectRef.empty')}
       disabled={disabled}
-      className={cn(className)}
+      // Fill the form column like every other input. Combobox's own
+      // `w-[200px]` is a component default that left this control stranded at
+      // a third of the row while `名称` beside it ran full width.
+      className={cn('w-full', className)}
     />
   );
 }

package/src/widgets/PeoplePicker.test.tsx

@@ -189,6 +189,26 @@ describe('PeoplePicker', () => {
     expect(onSelect).toHaveBeenCalledWith('u1');
   });
 
+  it('keyboard: cursor resets when the results are replaced by a search', async () => {
+    // Pins the semantics the render-phase reset must preserve: a NEW result
+    // set does not inherit the previous set's cursor. (The reset moved out of
+    // an effect into the render phase so it can never land AFTER a subsequent
+    // ArrowDown — the CI flake on the test above.)
+    const ds = makeDataSource();
+    render(
+      <PeoplePicker {...baseProps} dataSource={ds} onSelect={vi.fn()} onSelectRecords={vi.fn()} onOpenChange={vi.fn()} />,
+    );
+    await waitFor(() => expect(screen.getByText('Amy Lin')).toBeTruthy());
+    const search = screen.getByTestId('people-picker-search');
+    fireEvent.keyDown(search, { key: 'ArrowDown' });
+    await waitFor(() =>
+      expect(screen.getAllByTestId('person-row')[0].getAttribute('data-active')).toBe('true'),
+    );
+    fireEvent.change(search, { target: { value: 'bob' } });
+    await waitFor(() => expect(screen.getAllByTestId('person-row')).toHaveLength(1));
+    expect(screen.getAllByTestId('person-row')[0].getAttribute('data-active')).not.toBe('true');
+  });
+
   it('keyboard: Backspace on empty search removes the last chip (multi)', async () => {
     const ds = makeDataSource();
     render(

package/src/widgets/PeoplePicker.tsx

@@ -320,10 +320,22 @@ export function PeoplePicker({
     () => query.records.map(r => String(getPersonId(r, idField))).join(''),
     [query.records, idField],
   );
-  useEffect(() => {
+  // The reset runs in the RENDER PHASE (the "adjusting state during render"
+  // pattern), NOT in an effect. An effect flushes asynchronously after the
+  // render that delivered the records — so a reset queued by their arrival
+  // could land AFTER a subsequent ArrowDown and eat the just-set cursor.
+  // That is the residual ArrowDown→Enter flake the signature key above did
+  // not close (CI reproduced it under load), and a real fast-fingers UX bug:
+  // rows appear, the user presses ArrowDown, the highlight vanishes.
+  // Resetting during the same render that shows the new rows makes the
+  // ordering deterministic — by the time the rows are visible, the reset
+  // has already happened.
+  const cursorEpoch = `${query.search}\u0000${recordsSignature}`;
+  const [seenCursorEpoch, setSeenCursorEpoch] = useState(cursorEpoch);
+  if (seenCursorEpoch !== cursorEpoch) {
+    setSeenCursorEpoch(cursorEpoch);
     setActiveIndex(-1);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [query.search, recordsSignature]);
+  }
   // Keep it in range if the list shrinks.
   useEffect(() => {
     setActiveIndex(i => (i >= navList.length ? navList.length - 1 : i));

package/src/widgets/RadioField.tsx

@@ -85,10 +85,13 @@ export function RadioField({
       className={className}
     >
       {options.map((opt) => {
-        const id = `${groupId}-${opt.value}`;
+        // Radix speaks strings — stringify the (possibly numeric,
+        // #3090-widened) authored value at this boundary.
+        const value = String(opt.value);
+        const id = `${groupId}-${value}`;
         return (
-          <div key={opt.value} className="flex items-center space-x-2">
-            <RadioGroupItem value={opt.value} id={id} data-testid={`radio-option-${opt.value}`} />
+          <div key={value} className="flex items-center space-x-2">
+            <RadioGroupItem value={value} id={id} data-testid={`radio-option-${value}`} />
             <Label htmlFor={id} className="font-normal">{opt.label}</Label>
           </div>
         );

package/src/widgets/RecipientPickerField.test.tsx

@@ -0,0 +1,157 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * RecipientPickerField — the sharing-rule recipient picker (objectstack#3821).
+ *
+ * Two regressions are pinned here:
+ *  1. the candidate query must use the STRUCTURED `$orderby` form. It used to
+ *     pass the clause string `'name asc'`, which ApiDataSource walked
+ *     character by character into `0 n,1 a,2 m,…`; the server then sorted by
+ *     columns that don't exist and every recipient list came back empty, so
+ *     the control read "No matches" forever and no rule could be saved.
+ *  2. the placeholder must come from a per-type i18n key, not from
+ *     interpolating the enum value into an English sentence.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { RecipientPickerField } from './RecipientPickerField';
+
+const USERS = [
+  { id: 'usr_1', name: 'Ada Auditor' },
+  { id: 'usr_2', name: 'Bob Builder' },
+];
+
+function mockDataSource(rows: any[] = USERS) {
+  return { find: vi.fn().mockResolvedValue({ data: rows }) } as any;
+}
+
+function renderPicker(recipientType: string, dataSource: any, value = '') {
+  return render(
+    <RecipientPickerField
+      value={value}
+      onChange={vi.fn()}
+      field={{ name: 'recipient_id' } as any}
+      dataSource={dataSource}
+      dependentValues={{ recipient_type: recipientType }}
+    />,
+  );
+}
+
+describe('RecipientPickerField — candidate query', () => {
+  it('orders candidates with the structured $orderby form, never a clause string', async () => {
+    const ds = mockDataSource();
+    renderPicker('user', ds);
+
+    await waitFor(() => expect(ds.find).toHaveBeenCalled());
+    const [object, params] = ds.find.mock.calls[0];
+    expect(object).toBe('sys_user');
+    expect(params.$orderby).toEqual({ name: 'asc' });
+    // A bare string is what regressed; assert the shape explicitly.
+    expect(typeof params.$orderby).not.toBe('string');
+  });
+
+  it('queries the object mapped to each recipient type', async () => {
+    for (const [type, object] of [
+      ['user', 'sys_user'],
+      ['team', 'sys_team'],
+      ['business_unit', 'sys_business_unit'],
+      ['unit_and_subordinates', 'sys_business_unit'],
+      ['position', 'sys_position'],
+    ] as const) {
+      const ds = mockDataSource([]);
+      const { unmount } = renderPicker(type, ds);
+      await waitFor(() => expect(ds.find).toHaveBeenCalled());
+      expect(ds.find.mock.calls[0][0]).toBe(object);
+      unmount();
+    }
+  });
+
+  it('shows the loaded records as options once the list is opened', async () => {
+    const ds = mockDataSource();
+    renderPicker('user', ds);
+    await waitFor(() => expect(ds.find).toHaveBeenCalled());
+
+    fireEvent.click(screen.getByRole('combobox'));
+    expect(await screen.findByText('Ada Auditor')).toBeInTheDocument();
+    expect(screen.getByText('Bob Builder')).toBeInTheDocument();
+  });
+});
+
+describe('RecipientPickerField — keeping the stored recipient', () => {
+  function renderControlled(initialType: string, value: string, onChange: any) {
+    const ds = mockDataSource();
+    const view = render(
+      <RecipientPickerField
+        value={value}
+        onChange={onChange}
+        field={{ name: 'recipient_id' } as any}
+        dataSource={ds}
+        dependentValues={{ recipient_type: initialType }}
+      />,
+    );
+    const rerenderWith = (type: string) =>
+      view.rerender(
+        <RecipientPickerField
+          value={value}
+          onChange={onChange}
+          field={{ name: 'recipient_id' } as any}
+          dataSource={ds}
+          dependentValues={{ recipient_type: type }}
+        />,
+      );
+    return { ...view, rerenderWith };
+  }
+
+  it('keeps the saved recipient when the type arrives late (edit form hydrating)', async () => {
+    // The edit dialog mounts the widget before the record lands, so
+    // recipient_type is '' on the first render and 'user' on the next. That is
+    // hydration, not the admin changing the type — clearing there wiped the
+    // saved recipient and the blank got persisted on save.
+    const onChange = vi.fn();
+    const { rerenderWith } = renderControlled('', 'usr_1', onChange);
+    rerenderWith('user');
+    await waitFor(() => expect(onChange).not.toHaveBeenCalled());
+  });
+
+  it('clears the recipient when the admin actually switches type', async () => {
+    const onChange = vi.fn();
+    const { rerenderWith } = renderControlled('user', 'usr_1', onChange);
+    rerenderWith('team');
+    await waitFor(() => expect(onChange).toHaveBeenCalledWith(''));
+  });
+
+  it('does not clear when the type is unset back to empty', async () => {
+    const onChange = vi.fn();
+    const { rerenderWith } = renderControlled('user', 'usr_1', onChange);
+    rerenderWith('');
+    await waitFor(() => expect(onChange).not.toHaveBeenCalled());
+  });
+});
+
+describe('RecipientPickerField — localizable copy', () => {
+  it('takes the placeholder from a per-type key rather than the raw enum value', async () => {
+    // With no I18nProvider the widget falls back to the English defaults, so
+    // the assertion is on the *wording*: 'Select a business unit' can only come
+    // from the keyed string — interpolating the enum produced
+    // 'Select a business unit' only by accident and 'Select a unit and
+    // subordinates' for the next type over.
+    const ds = mockDataSource([]);
+    renderPicker('unit_and_subordinates', ds);
+    await waitFor(() => expect(ds.find).toHaveBeenCalled());
+    expect(await screen.findByText('Select a business unit')).toBeInTheDocument();
+    expect(screen.queryByText(/unit and subordinates/i)).not.toBeInTheDocument();
+  });
+
+  it('prompts for a recipient type before one is chosen', () => {
+    renderPicker('', mockDataSource([]));
+    expect(screen.getByText('Select a recipient type first.')).toBeInTheDocument();
+  });
+});