Merge pull request #1073 from objectstack-ai/copilot/upgrade-record-picker-solution

Author: hotlong

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **RecordPickerDialog Component** (`@object-ui/fields`): New enterprise-grade record selection dialog with multi-column table display, pagination, search, column sorting with `$orderby`, keyboard navigation (Arrow keys + Enter), loading/error/empty states, and single/multi-select support. Responsive layout with mobile-friendly width. Provides the foundation for Salesforce-style Lookup experience.
+- **LookupField Popover Typeahead** (`@object-ui/fields`): Level 1 quick-select upgraded from Dialog to Popover for inline typeahead experience (anchored dropdown, not modal). Includes "Show All Results" footer button that opens the full RecordPickerDialog (Level 2).
+- **LookupFieldMetadata Schema Enhancement** (`@object-ui/types`): Added `lookup_columns`, `description_field`, `lookup_page_size`, `lookup_filters` to `LookupFieldMetadata`. New `LookupColumnDef` interface with `type` hint for cell formatting. New `LookupFilterDef` interface for base filter configuration.
+
 ### Changed
 
 - **@objectstack v3.2.6 Upgrade**: Upgraded all `@objectstack/*` packages from `^3.2.5` to `^3.2.6` across 13 package.json files (43 references)

ROADMAP.md

@@ -134,6 +134,7 @@ ObjectUI is a universal Server-Driven UI (SDUI) engine built on React + Tailwind
 - [x] Lookup field dynamic DataSource loading — popup fetches records via `DataSource.find()` with `$search` debounce, loading/error/empty states
 - [x] Lookup field context DataSource — reads DataSource from SchemaRendererContext so forms work without explicit prop
 - [x] Lookup field UX polish — arrow key navigation, description field display, quick-create entry, ARIA listbox roles
+- [x] Enterprise Record Picker — `RecordPickerDialog` component with multi-column table, pagination, search; LookupField two-level interaction (quick-select + "Show All Results" → full picker); `lookup_columns` / `lookup_page_size` schema config
 - [ ] Form conditional logic with branching
 - [ ] Multi-page forms with progress indicator
 

content/docs/fields/lookup.mdx

@@ -73,6 +73,16 @@ interface LookupFieldSchema {
 
   // Quick-create callback (shown when no results found)
   onCreateNew?: (searchQuery: string) => void;
+
+  // === Record Picker Configuration (Enterprise) ===
+  
+  // Columns to show in the Record Picker dialog table.
+  // Accepts field names or { field, label, width } objects.
+  // When omitted, auto-infers from reference_field.
+  lookup_columns?: Array<string | { field: string; label?: string; width?: string }>;
+
+  // Custom page size for the Record Picker dialog (default: 10)
+  lookup_page_size?: number;
 }
 
 interface LookupOption {
@@ -106,6 +116,41 @@ The popup will:
 2. Send `$search` queries with 300ms debounce as the user types
 3. Show loading spinner, error state with retry, and empty state
 4. Display "Showing X of Y" when more records exist than the page size
+5. Show a **"Show All Results"** button to open the full Record Picker dialog
+
+## Record Picker Dialog (Enterprise)
+
+When more results are available than displayed in the quick-select popup, a **"Show All Results"** button opens the full **RecordPickerDialog** — an enterprise-grade record selection experience.
+
+```plaintext
+// Configure the Record Picker with lookup_columns
+{
+  type: 'lookup',
+  name: 'order',
+  label: 'Order',
+  reference_to: 'orders',
+  reference_field: 'order_number',
+  description_field: 'customer_name',
+  lookup_columns: [
+    { field: 'order_number', label: 'Order #' },
+    { field: 'customer_name', label: 'Customer' },
+    { field: 'total_amount', label: 'Amount' },
+    { field: 'status', label: 'Status' },
+  ],
+  lookup_page_size: 15,
+}
+```
+
+The Record Picker dialog provides:
+- **Multi-column table** with configurable columns via `lookup_columns`
+- **Search** with debounced server-side querying
+- **Column sorting** via clickable headers (sends `$orderby` to DataSource)
+- **Pagination** with page-by-page navigation
+- **Keyboard navigation** — Arrow keys to move between rows, Enter/Space to select
+- **Single/Multi-select** with visual check indicators and confirmation flow
+- **Responsive layout** — Mobile-friendly width (95vw on small screens)
+- **Loading, error, and empty states**
+- Auto-inferred columns from `reference_field` when `lookup_columns` is not set
 
 ## Lookup vs Master-Detail
 
@@ -133,12 +178,19 @@ import { LookupCellRenderer } from '@object-ui/fields';
 
 ## Features
 
+- **Two-Level Interaction**: Popover typeahead (Level 1) + full Record Picker dialog (Level 2)
+- **Record Picker Dialog**: Enterprise-grade table with multi-column, pagination, search, sorting
+- **Inline Popover**: Level 1 opens as anchored dropdown (non-modal) for fast typeahead
+- **Column Sorting**: Clickable column headers with `$orderby` server-side sort
 - **Dynamic DataSource Loading**: Automatically fetches records from referenced objects
 - **Search**: Debounced type-ahead search with `$search` parameter
-- **Multi-Select**: Support for multiple references
-- **Keyboard Navigation**: Arrow keys to navigate, Enter to select
+- **Multi-Select**: Support for multiple references with confirmation flow
+- **Keyboard Navigation**: Arrow keys to navigate rows, Enter to select in both levels
+- **Responsive**: Mobile-friendly width, adapts to screen size
 - **Loading/Error/Empty States**: Friendly feedback for all states
 - **Secondary Field Display**: Show description/subtitle per option
 - **Quick-Create Entry**: Optional "Create new" button when no results
-- **Pagination Hint**: Shows total count when more results available
+- **Configurable Columns**: `lookup_columns` for multi-column picker display
+- **Base Filters**: `lookup_filters` to restrict selectable records
+- **Pagination**: Page-by-page navigation in Record Picker dialog
 - **Backward Compatible**: Falls back to static options when no DataSource

packages/fields/src/index.tsx

@@ -1327,6 +1327,7 @@ export * from './widgets/PasswordField';
 export * from './widgets/TextAreaField';
 export * from './widgets/RichTextField';
 export * from './widgets/LookupField';
+export * from './widgets/RecordPickerDialog';
 export * from './widgets/FileField';
 export * from './widgets/ImageField';
 export * from './widgets/LocationField';