fix(plugin-grid): bulk-action params render the shared form field widgets — lookup errors get Retry, sys_user params get the PeoplePicker (#3064, ADR-0059) (#3073)

BulkActionDialog's params step was a hand-rolled 2026-05 MVP: lookup params
eagerly fetched find(object, {$top:200}) once per param name, swallowed any
fetch error into an empty option list, rendered that emptiness as a permanent
"Loading…" placeholder, and cached the failure per param name so reopening the
dialog never retried (#3064). It also predated the PeoplePicker (#2112), so a
person param looked nothing like the form's person field.

Params now render through the SAME field-widget renderer the object form and
ActionParamDialog use (completing ADR-0059 for the bulk surface): a new pure
bulkParamToField() adapter translates each BulkActionParam to field metadata,
getLazyFieldWidget() supplies the lazy widget, and only picker widgets get the
grid DataSource threaded in. A sys_user-targeting lookup (or a user-typed
param) is promoted to the form's search-first PeoplePicker; other lookups get
the searchable LookupField whose useRecordQuery kernel owns loading/error/
empty states and refetches on every open — the #3064 pipeline (eager prefetch
→ swallowed error → permanent Loading… → poisoned cache) is gone by
construction. Confirm-step labels are resolved per selected id via findOne,
replacing the removed candidate prefetch; #2204 schema-fallback multi
semantics, required gating, and the #2185 popper guard are preserved (all
pinned by tests, plus browser-verified via the demo's new picker defs and
?failUsers=1 failure toggle).

Closes #3064

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: baozhoutao

.changeset/bulk-dialog-shared-field-widgets.md

@@ -0,0 +1,26 @@
+---
+"@object-ui/plugin-grid": patch
+---
+
+fix(grid): bulk-action params render the shared form field widgets — a failed lookup fetch shows an error + Retry instead of a permanent "Loading…" (#3064, ADR-0059)
+
+`BulkActionDialog`'s hand-rolled param controls (a 2026-05 MVP predating the
+PeoplePicker and ADR-0059) are replaced by the same field-widget renderer the
+object form and `ActionParamDialog` use, via a new pure `bulkParamToField()`
+adapter + `getLazyFieldWidget()`:
+
+- `lookup` params get the real searchable `LookupField` (server-side search,
+  record-picker dialog, loading/error/empty states owned by `useRecordQuery`);
+  a `sys_user` target — or a `user`-typed param — is promoted to the form's
+  search-first PeoplePicker (avatar + subtitle rows, recents, banned users
+  excluded). Every other param type (date/datetime/boolean/select/multiselect/
+  textarea/number/…) renders its form widget too, so param support can no
+  longer drift behind the form surface.
+- The #3064 failure pipeline is gone by construction: no more eager
+  `find($top:200)` prefetch on open, no error swallowed into an empty option
+  list rendering as permanent "Loading…", and no per-param failure cache —
+  reopening or Retry refetches.
+- Preserved semantics: #2204 schema-fallback multi-value detection, required
+  gating, #2185 nested-popper dismissal guard, and human-readable confirm-step
+  labels (now resolved per selected id via `findOne`, replacing the removed
+  candidate prefetch).

packages/plugin-grid/demo/bulk-actions.tsx

@@ -20,6 +20,13 @@
  *      by-name dispatch — it must still render ALONGSIDE the two defs above.
  *   3. Record `t3` fails server-side (422), proving per-record attribution: the
  *      result panel reports 4/5 with an error row rather than a blanket success.
+ *   4. Rich `bulkActionDefs` with picker params (#3064 / ADR-0059): `Set
+ *      Manager` (lookup → sys_user, single) and `Assign Executors` (lookup →
+ *      sys_user, multiple) must render the form's PeoplePicker; `Set Queue`
+ *      (lookup → demo_queue) the searchable LookupField. Open with
+ *      `?failUsers=1` to make the FIRST sys_user candidate fetch fail — the
+ *      picker must show an error + Retry (never a permanent "Loading…"), and
+ *      Retry / reopening must refetch.
  */
 import * as React from 'react';
 import { createRoot } from 'react-dom/client';
@@ -90,11 +97,57 @@ const RECALC = {
   ],
 };
 
+/** Candidate directories for the picker-param defs (#3064). */
+const USERS = [
+  { id: 'u1', name: '现场工人-测试', email: 'worker@demo.dev' },
+  { id: 'u2', name: '工厂长-测试', email: 'chief@demo.dev' },
+  { id: 'u3', name: '质检员-测试', email: 'qa@demo.dev' },
+  { id: 'u4', name: 'Dev Admin', email: 'admin@demo.dev' },
+];
+const QUEUES = [
+  { id: 'q1', title: 'Frontline support' },
+  { id: 'q2', title: 'Escalations' },
+];
+
+// `?failUsers=1` — the first sys_user candidate fetch rejects, later ones
+// succeed: the manual repro for #3064 (error + Retry, no failure caching).
+let failNextUserFetch = new URLSearchParams(location.search).has('failUsers');
+
+function searchable(rows: Array<Record<string, any>>, params: any) {
+  const q = typeof params?.$search === 'string' ? params.$search.trim().toLowerCase() : '';
+  const data = q
+    ? rows.filter(r => Object.values(r).some(v => String(v).toLowerCase().includes(q)))
+    : rows;
+  return { data: data.map(r => ({ ...r })), total: data.length, hasMore: false, pageSize: 50 };
+}
+
 const dataSource: any = {
-  async find() {
+  async find(resource: string, params: any) {
+    if (resource === 'sys_user') {
+      if (failNextUserFetch) {
+        failNextUserFetch = false;
+        throw new Error('sys_user directory unavailable (simulated)');
+      }
+      return searchable(USERS, params);
+    }
+    if (resource === 'demo_queue') return searchable(QUEUES, params);
     return { data: ROWS.map(r => ({ ...r })), total: ROWS.length, hasMore: false, pageSize: 50 };
   },
+  async findOne(resource: string, id: string) {
+    const pool = resource === 'sys_user' ? USERS : resource === 'demo_queue' ? QUEUES : ROWS;
+    return pool.find(r => r.id === id) ?? null;
+  },
+  async update(resource: string, id: string, patch: Record<string, unknown>) {
+    pushLog({ url: `(update ${resource})`, recordId: id, params: JSON.stringify(patch), status: 200 });
+    return { id, ...patch };
+  },
   async getObjectSchema(name: string) {
+    if (name === 'sys_user') {
+      return { name, label: 'User', fields: { id: { type: 'text' }, name: { type: 'text', label: 'Name' }, email: { type: 'email', label: 'Email' } } };
+    }
+    if (name === 'demo_queue') {
+      return { name, label: 'Queue', fields: { id: { type: 'text' }, title: { type: 'text', label: 'Title' } } };
+    }
     return {
       name,
       label: 'Task',
@@ -170,6 +223,33 @@ const schema: any = {
   pagination: { pageSize: 50 },
   // Bare names: two resolve to declared actions, one doesn't.
   bulkActions: ['bulk_mark_done', 'bulk_recalc_estimate', 'legacy_only_handler'],
+  // Rich defs with picker params — the shared-field-widget surface (#3064).
+  bulkActionDefs: [
+    {
+      name: 'set_manager',
+      label: 'Set Manager',
+      operation: 'update',
+      params: [
+        { name: 'manager', label: 'Manager', type: 'lookup', object: 'sys_user', required: true },
+      ],
+    },
+    {
+      name: 'assign_executors',
+      label: 'Assign Executors',
+      operation: 'update',
+      params: [
+        { name: 'executors', label: 'Executors', type: 'lookup', object: 'sys_user', multiple: true, required: true },
+      ],
+    },
+    {
+      name: 'set_queue',
+      label: 'Set Queue',
+      operation: 'update',
+      params: [
+        { name: 'queue', label: 'Queue', type: 'lookup', object: 'demo_queue', labelField: 'title', required: true },
+      ],
+    },
+  ],
 };
 
 function Demo() {

packages/plugin-grid/src/__tests__/bulkActionDialogParams.test.tsx

@@ -7,14 +7,18 @@
  */
 
 /**
- * BulkActionDialog param widgets (#2185): the bulk-edit dialog previously only
- * rendered single-value controls, so a multi-value backend field (e.g. a
- * multi-user `executors`) could not be set — the picker collapsed to one value
- * and overwrote the array. These tests pin the multi-select path end-to-end
- * (empty-array required-gating → pick many → array patch → label preview) plus
- * the new date widget.
+ * BulkActionDialog param widgets.
+ *
+ * #2185/#2204 pinned the multi-value path (empty-array required-gating → pick
+ * many → array patch → label preview) and the date widget. Since the ADR-0059
+ * migration (#3064) params render through the SHARED form field widgets
+ * (`@object-ui/fields` via `bulkParamToField`), so these tests now assert the
+ * form-widget DOM (multiselect toggle chips, native date input) — and the new
+ * lookup suite pins the #3064 contract itself: no eager candidate prefetch,
+ * fetch errors surfaced with a Retry affordance, and no failure caching
+ * (reopening the picker refetches).
  */
-import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';
 import { render, screen, waitFor, fireEvent } from '@testing-library/react';
 import '@testing-library/jest-dom';
 import React from 'react';
@@ -34,6 +38,20 @@ beforeAll(() => {
   }
 });
 
+beforeEach(() => {
+  // happy-dom lacks matchMedia; the lookup widgets' useIsMobile needs it.
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    addListener: () => {},
+    removeListener: () => {},
+    dispatchEvent: () => false,
+  })) as any;
+});
+
 function makeDataSource() {
   const update = vi.fn(async () => ({}));
   const del = vi.fn(async () => ({}));
@@ -77,10 +95,10 @@ describe('BulkActionDialog — multi-select param produces an array patch', () =
     const next = screen.getByRole('button', { name: 'Next' });
     expect(next).toBeDisabled();
 
-    // Open the multi-select popover and pick both options.
-    fireEvent.click(screen.getByRole('combobox'));
-    fireEvent.click(await screen.findByText('Red'));
-    fireEvent.click(await screen.findByText('Blue'));
+    // The shared MultiSelectField renders toggle chips (same as the form) —
+    // await them through the lazy-widget Suspense boundary, then pick both.
+    fireEvent.click(await screen.findByTestId('multiselect-option-red'));
+    fireEvent.click(await screen.findByTestId('multiselect-option-blue'));
 
     // Now valid → advance to confirm.
     await waitFor(() => expect(next).toBeEnabled());
@@ -100,7 +118,7 @@ describe('BulkActionDialog — multi-select param produces an array patch', () =
 });
 
 describe('BulkActionDialog — date param renders a date picker', () => {
-  it('renders a native date input rather than a free-text box', () => {
+  it('renders a native date input rather than a free-text box', async () => {
     const ds = makeDataSource();
     const def: any = {
       name: 'set_due',
@@ -118,8 +136,70 @@ describe('BulkActionDialog — date param renders a date picker', () => {
         onClose={() => {}}
       />,
     );
-    // Radix Dialog portals its content to document.body, not the render root.
-    const dateInput = document.querySelector('input[type="date"]');
-    expect(dateInput).toBeInTheDocument();
+    // Radix Dialog portals to document.body, and the widget loads lazily.
+    await waitFor(() => {
+      expect(document.querySelector('input[type="date"]')).toBeInTheDocument();
+    });
+  });
+});
+
+describe('BulkActionDialog — lookup param uses the shared record picker (#3064)', () => {
+  const lookupDef: any = {
+    name: 'assign_queue',
+    label: 'Assign queue',
+    operation: 'update',
+    params: [
+      { name: 'queue', label: 'Queue', type: 'lookup', object: 'queues', required: true },
+    ],
+  };
+
+  it('does not prefetch candidates when the dialog opens', async () => {
+    const ds = makeDataSource();
+    ds.find = vi.fn(async () => ({ data: [], total: 0 }));
+    render(
+      <BulkActionDialog
+        def={lookupDef}
+        rows={[{ id: 'r1' }]}
+        resource="thing"
+        dataSource={ds}
+        open
+        onClose={() => {}}
+      />,
+    );
+    // The picker trigger renders (lazy widget) with no candidate query issued —
+    // the old dialog fired find(object, {$top: 200}) on open.
+    await screen.findByTestId('lookup-trigger-queue');
+    expect(ds.find).not.toHaveBeenCalled();
+  });
+
+  it('surfaces a failed candidate fetch and retries instead of caching the failure', async () => {
+    const ds = makeDataSource();
+    ds.find = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('boom'))
+      .mockResolvedValue({ data: [{ id: 'q1', name: 'Support queue' }], total: 1 });
+    render(
+      <BulkActionDialog
+        def={lookupDef}
+        rows={[{ id: 'r1' }]}
+        resource="thing"
+        dataSource={ds}
+        open
+        onClose={() => {}}
+      />,
+    );
+
+    // Open the picker → the fetch fails → an error state with a Retry
+    // affordance renders (previously: a permanent "Loading…" placeholder).
+    fireEvent.click(await screen.findByTestId('lookup-trigger-queue'));
+    const alert = await screen.findByRole('alert');
+    expect(alert.textContent).toContain('boom');
+    expect(ds.find).toHaveBeenCalledTimes(1);
+
+    // Retry refetches (previously: the failure was cached per param name and
+    // no further request was ever issued) and the candidates render.
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }));
+    await screen.findByText('Support queue');
+    expect(ds.find).toHaveBeenCalledTimes(2);
   });
 });

packages/plugin-grid/src/__tests__/bulkActionSchemaMultiple.test.tsx

@@ -127,11 +127,11 @@ describe('BulkActionDialog — schema fallback when param.multiple is omitted (#
       />,
     );
 
-    // Schema says multi → the combobox (Popover multi-select) renders, not a
-    // single-select trigger that collapses to one value.
-    fireEvent.click(screen.getByRole('combobox'));
-    fireEvent.click(await screen.findByText('Frontend'));
-    fireEvent.click(await screen.findByText('Design'));
+    // Schema says multi → the shared MultiSelectField (toggle chips) renders,
+    // not a single-select trigger that collapses to one value.
+    await screen.findByTestId('multiselect-labels');
+    fireEvent.click(screen.getByTestId('multiselect-option-frontend'));
+    fireEvent.click(screen.getByTestId('multiselect-option-design'));
 
     const next = screen.getByRole('button', { name: 'Next' });
     await waitFor(() => expect(next).toBeEnabled());