@object-ui/fields 16.1.0 → 17.2.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

@@ -10,7 +10,7 @@ import { cn,
   PopoverTrigger,
   PopoverContent, EmptyValue } from '@object-ui/components';
 import { Search, X, Loader2, AlertCircle, Plus, TableProperties } from 'lucide-react';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 import type { DataSource, QueryParams, LookupColumnDef } from '@object-ui/types';
 import { RecordPickerDialog, lookupFiltersToRecord } from './RecordPickerDialog';
 import type { RecordPickerFilterColumn } from './RecordPickerDialog';
@@ -191,7 +191,7 @@ function mapFieldTypeToFilterType(
  * from the referenced object using `DataSource.find()`.
  * Falls back to static `options` when no DataSource is available.
  */
-export function LookupField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
+export function LookupField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<any>) {
   const [isOpen, setIsOpen] = useState(false);
   const { t } = useFieldTranslation();
   const listboxId = React.useId();
@@ -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);
@@ -274,13 +280,13 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   }, [fieldMeta?.depends_on, fieldMeta?.dependsOn]);
 
   // Resolve dependent field values from explicit prop or SchemaRendererContext.data
-  const dependentValuesProp = (props as any).dependentValues as Record<string, any> | undefined;
+  const dependentValuesProp = props.dependentValues;
 
   // Resolve DataSource: explicit prop > field-level > wrapper field > SchemaRendererContext > none
   const ctx = useContext(SchemaRendererContext);
   const contextDataSource = ctx?.dataSource ?? null;
   const dataSource: DataSource | null =
-    (props as any).dataSource ?? lookupField?.dataSource ?? fieldMeta?.dataSource ?? contextDataSource;
+    (props.dataSource as DataSource | null | undefined) ?? lookupField?.dataSource ?? fieldMeta?.dataSource ?? contextDataSource;
 
   /** Resolve dependent values from the explicit prop (preferred), the form-data
    *  context provided by @object-ui/react, or finally `ctx.data` (record scope). */
@@ -363,7 +369,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
 
   // Optional create-new callback
   const onCreateNew: ((searchQuery: string) => void) | undefined =
-    (props as any).onCreateNew ?? lookupField?.onCreateNew;
+    props.onCreateNew ?? lookupField?.onCreateNew;
 
   // State for the full Record Picker dialog (Level 2)
   const [isPickerOpen, setIsPickerOpen] = useState(false);
@@ -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) : [];
@@ -584,7 +657,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   // auto-fill sibling fields from it — e.g. a line-item grid copying a product's
   // unit_price/description when the item is chosen. When provided (single
   // select), it drives the update and the host owns the resulting value change.
-  const onSelectRecord = (props as any).onSelectRecord as ((record: LookupOption) => void) | undefined;
+  const onSelectRecord = props.onSelectRecord;
 
   const handleSelect = useCallback(
     (option: LookupOption) => {
@@ -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 />;
     }
 
@@ -822,7 +906,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   // Compact mode (e.g. inside a line-item grid cell): show the selected value
   // INSIDE a borderless trigger on a single line — no chip stacked above a
   // separate "Select…" button (which double-stacks and wastes the row height).
-  const compact = !!(props as any).compact;
+  const compact = !!props.compact;
   const singleSelectedLabel = selectedOptions[0]?.label || selectedOptions[0]?.[displayField];
 
   // Shared field trigger — the anchor for either the inline PeoplePicker
@@ -836,21 +920,34 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
         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')}
+      disabled={dependenciesMissing || props.disabled}
+      data-testid={dependenciesMissing ? 'lookup-trigger-gated' : ((props.name || lookupField?.name) ? `lookup-trigger-${props.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')} />
+      {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>
   );
@@ -1117,7 +1214,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
           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}
+          disabled={dependenciesMissing || props.disabled}
           onClick={() => setIsPickerOpen(true)}
           aria-label={t('lookup.browseAll')}
           title={dependenciesMissing

package/src/widgets/MasterDetailField.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { Button, Badge, cn } from '@object-ui/components';
 import { Plus, X, ExternalLink } from 'lucide-react';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * Master-Detail relationship data structure
@@ -23,7 +23,7 @@ export function MasterDetailField({
   readonly,
   className,
   ...props 
-}: FieldWidgetProps<MasterDetailValue[]>) {
+}: FieldWidgetComponentProps<MasterDetailValue[]>) {
   const items = value || [];
   const config = field || (props as any).schema;
 

package/src/widgets/MultiSelectField.tsx

@@ -1,7 +1,7 @@
 import React, { useEffect } from 'react';
 import { Badge, EmptyValue, cn } from '@object-ui/components';
 import type { OptionLike } from '@object-ui/core';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 import { useCascadingOptions } from './useCascadingOptions';
 
 interface Option extends OptionLike { color?: string }
@@ -32,11 +32,11 @@ export function MultiSelectField({
   emptyHint: _emptyHint,
   dataSource: _dataSource,
   ...props
-}: FieldWidgetProps<string[]>) {
+}: FieldWidgetComponentProps<string[]>) {
   const config = (field || schema) as any;
   const rawOptions: Option[] = config?.options || [];
   const selected: string[] = Array.isArray(value) ? value : value == null ? [] : [value as unknown as string];
-  const fieldName = (props as any).name || config?.name || (props as any).id || '';
+  const fieldName = props.name || config?.name || props.id || '';
 
   const dependsOn = config?.dependsOn ?? dependsOnProp;
   const { options, gated, dependsOnFields } = useCascadingOptions<Option>(
@@ -98,13 +98,16 @@ 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)}
-            disabled={(props as any).disabled}
+            key={value}
+            onClick={() => toggle(value)}
+            disabled={props.disabled}
             aria-pressed={active}
             data-testid={`multiselect-option-${opt.value}`}
             className={cn(

package/src/widgets/NumberField.tsx

@@ -1,13 +1,13 @@
 import React from 'react';
 import { Input, EmptyValue } from '@object-ui/components';
 import { NumberFieldMetadata } from '@object-ui/types';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * NumberField - Numeric input with optional decimal precision
  * Supports min/max/step constraints and configurable decimal precision
  */
-export function NumberField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<number>) {
+export function NumberField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<number>) {
   if (readonly) {
     return value == null ? <EmptyValue /> : <span className="text-sm">{value}</span>;
   }

package/src/widgets/ObjectField.tsx

@@ -1,12 +1,12 @@
 import React, { useState, useEffect } from 'react';
 import { Textarea, cn, EmptyValue } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * ObjectField - JSON object editor
  * Allows editing structured JSON data
  */
-export function ObjectField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
+export function ObjectField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<any>) {
   const config = field || (props as any).schema;
   
   // Initialize string state based on value

package/src/widgets/ObjectRefField.tsx

@@ -1,7 +1,8 @@
 import React from 'react';
 import { Combobox, EmptyValue, cn } from '@object-ui/components';
 import { SchemaRendererContext } from '@object-ui/react';
-import type { FieldWidgetProps } from './types';
+import type { FieldWidgetComponentProps } from './types';
+import { useFieldTranslation } from './useFieldTranslation';
 
 /**
  * ObjectRefField — object-name picker for form fields that store the machine
@@ -31,10 +32,11 @@ export function ObjectRefField({
   readonly,
   className,
   ...props
-}: FieldWidgetProps<string>) {
+}: FieldWidgetComponentProps<string>) {
   const ctx = React.useContext(SchemaRendererContext);
-  const dataSource: any = (props as any).dataSource ?? (ctx as any)?.dataSource ?? null;
-  const disabled = (props as any).disabled as boolean | undefined;
+  const { t } = useFieldTranslation();
+  const dataSource: any = props.dataSource ?? (ctx as any)?.dataSource ?? null;
+  const disabled = props.disabled;
 
   const [objects, setObjects] = React.useState<ObjectHeader[] | null>(null);
 
@@ -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/PasswordField.tsx

@@ -2,13 +2,13 @@ import React, { useState } from 'react';
 import { Input } from '@object-ui/components';
 import { Button } from '@object-ui/components';
 import { Eye, EyeOff } from 'lucide-react';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * PasswordField - Secure password input with visibility toggle
  * Includes show/hide toggle button and masks value in readonly mode
  */
-export function PasswordField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string>) {
+export function PasswordField({ value, onChange, field, readonly, className, ...props }: FieldWidgetComponentProps<string>) {
   const [showPassword, setShowPassword] = useState(false);
   const config = field || (props as any).schema;
 

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));