feat: address gap analysis — Popover typeahead, column sorting, keyboard nav, responsive, lookup_filters

- Convert LookupField Level 1 from Dialog to Popover for inline typeahead (Salesforce pattern)
- Add column sorting with $orderby to RecordPickerDialog (clickable headers, aria-sort)
- Add keyboard navigation (Arrow keys + Enter/Space) to RecordPickerDialog table
- Add responsive dialog width (95vw mobile, max-w-2xl desktop)
- Add LookupFilterDef type and lookup_filters to LookupFieldMetadata schema
- Add type hint to LookupColumnDef for future getCellRenderer integration
- Add 5 new tests for sorting, keyboard nav, responsive layout
- Update CHANGELOG.md and lookup.mdx documentation

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -9,9 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **RecordPickerDialog Component** (`@object-ui/fields`): New enterprise-grade record selection dialog with multi-column table display, pagination, search, loading/error/empty states, and single/multi-select support. Provides the foundation for Salesforce-style Lookup experience.
-- **LookupField Two-Level Interaction** (`@object-ui/fields`): LookupField now supports a "Show All Results" button in the quick-select dialog that opens the full RecordPickerDialog with table view, pagination, and multi-column display.
-- **LookupFieldMetadata Schema Enhancement** (`@object-ui/types`): Added `lookup_columns`, `description_field`, `lookup_page_size` properties to `LookupFieldMetadata` for configuring the Record Picker display. New `LookupColumnDef` interface for typed column definitions.
+- **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
 

content/docs/fields/lookup.mdx

@@ -144,8 +144,11 @@ When more results are available than displayed in the quick-select popup, a **"S
 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
-- **Single/Multi-select** with visual check indicators
+- **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
 
@@ -175,15 +178,19 @@ import { LookupCellRenderer } from '@object-ui/fields';
 
 ## Features
 
-- **Two-Level Interaction**: Quick-select popup + full Record Picker dialog
-- **Record Picker Dialog**: Enterprise-grade table with multi-column, pagination, search
+- **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
 - **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/record-picker.test.tsx

@@ -438,3 +438,191 @@ describe('LookupField — Show All Results', () => {
     });
   });
 });
+
+// ------------- RecordPickerDialog — Column Sorting -------------
+
+describe('RecordPickerDialog — Column Sorting', () => {
+  const basePickerProps = {
+    open: true,
+    onOpenChange: vi.fn(),
+    dataSource: mockDataSource as any,
+    objectName: 'customers',
+    onSelect: vi.fn(),
+  };
+
+  it('sends $orderby when a column header is clicked', async () => {
+    mockDataSource.find.mockResolvedValue({
+      data: [
+        { id: '1', name: 'Acme Corp', email: 'acme@test.com' },
+        { id: '2', name: 'Beta Inc', email: 'beta@test.com' },
+      ],
+      total: 2,
+    });
+
+    render(
+      <RecordPickerDialog
+        {...basePickerProps}
+        columns={['name', 'email']}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Acme Corp')).toBeInTheDocument();
+    });
+
+    // Click the "Name" column header to sort
+    await act(async () => {
+      fireEvent.click(screen.getByText('Name'));
+    });
+
+    await waitFor(() => {
+      expect(mockDataSource.find).toHaveBeenCalledWith('customers', {
+        $top: 10,
+        $skip: 0,
+        $orderby: { name: 'asc' },
+      });
+    });
+  });
+
+  it('toggles sort direction on repeated column header click', async () => {
+    mockDataSource.find.mockResolvedValue({
+      data: [{ id: '1', name: 'Acme Corp' }],
+      total: 1,
+    });
+
+    render(
+      <RecordPickerDialog
+        {...basePickerProps}
+        columns={['name']}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Acme Corp')).toBeInTheDocument();
+    });
+
+    // First click: asc
+    await act(async () => {
+      fireEvent.click(screen.getByText('Name'));
+    });
+
+    await waitFor(() => {
+      expect(mockDataSource.find).toHaveBeenCalledWith('customers', expect.objectContaining({
+        $orderby: { name: 'asc' },
+      }));
+    });
+
+    // Second click: desc
+    await act(async () => {
+      fireEvent.click(screen.getByText('Name'));
+    });
+
+    await waitFor(() => {
+      expect(mockDataSource.find).toHaveBeenCalledWith('customers', expect.objectContaining({
+        $orderby: { name: 'desc' },
+      }));
+    });
+  });
+
+  it('renders sort indicators on column headers', async () => {
+    mockDataSource.find.mockResolvedValue({
+      data: [{ id: '1', name: 'Acme', email: 'test@test.com' }],
+      total: 1,
+    });
+
+    render(
+      <RecordPickerDialog
+        {...basePickerProps}
+        columns={['name', 'email']}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Acme')).toBeInTheDocument();
+    });
+
+    // Column headers should have aria-sort="none" initially
+    const nameHeader = screen.getByText('Name').closest('th');
+    expect(nameHeader).toHaveAttribute('aria-sort', 'none');
+
+    // Click to sort
+    await act(async () => {
+      fireEvent.click(screen.getByText('Name'));
+    });
+
+    await waitFor(() => {
+      expect(nameHeader).toHaveAttribute('aria-sort', 'ascending');
+    });
+  });
+});
+
+// ------------- RecordPickerDialog — Keyboard Navigation -------------
+
+describe('RecordPickerDialog — Keyboard Navigation', () => {
+  const basePickerProps = {
+    open: true,
+    onOpenChange: vi.fn(),
+    dataSource: mockDataSource as any,
+    objectName: 'customers',
+    onSelect: vi.fn(),
+  };
+
+  it('navigates rows with arrow keys and selects with Enter', async () => {
+    const onSelect = vi.fn();
+    const onOpenChange = vi.fn();
+
+    mockDataSource.find.mockResolvedValue({
+      data: [
+        { id: '1', name: 'Alpha' },
+        { id: '2', name: 'Beta' },
+        { id: '3', name: 'Gamma' },
+      ],
+      total: 3,
+    });
+
+    render(
+      <RecordPickerDialog
+        {...basePickerProps}
+        onSelect={onSelect}
+        onOpenChange={onOpenChange}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Alpha')).toBeInTheDocument();
+    });
+
+    // Focus the table container (has role="grid")
+    const gridContainer = screen.getByRole('grid');
+    gridContainer.focus();
+
+    // Arrow down twice: -1 → 0 (Alpha) → 1 (Beta)
+    await act(async () => {
+      fireEvent.keyDown(gridContainer, { key: 'ArrowDown' });
+    });
+    await act(async () => {
+      fireEvent.keyDown(gridContainer, { key: 'ArrowDown' });
+    });
+
+    // Press Enter to select Beta
+    await act(async () => {
+      fireEvent.keyDown(gridContainer, { key: 'Enter' });
+    });
+
+    expect(onSelect).toHaveBeenCalledWith('2');
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it('renders responsive dialog with mobile-friendly width', async () => {
+    mockDataSource.find.mockResolvedValue({ data: [], total: 0 });
+
+    render(<RecordPickerDialog {...basePickerProps} />);
+
+    await waitFor(() => {
+      const dialog = screen.getByTestId('record-picker-dialog');
+      expect(dialog).toBeInTheDocument();
+      // Check responsive classes are applied
+      expect(dialog.className).toContain('w-[95vw]');
+    });
+  });
+});