@@ -0,0 +1,30 @@
+---
+"@object-ui/components": patch
+---
+
+fix(components): FilterBuilder 的 lookup 列不再因 `options: []` 被拒掉远程搜索 (objectui#5031)
+
+`renderValueInput` 里那条远程 picker 分支的条件写的是 `!field?.options`,而 `[]`
+是真值 —— 于是一个带 `referenceTo`、`options` 为空数组的 lookup 列**进不到**
+`LookupValuePicker`,落进按 options 画的分支:标量算子得到一个候选数为 0 的
+Select(没有搜索框),`in` / `notIn` 得到一个空的勾选框列表。用户在这一列上挑不出
+任何**新**值,而同一列若 `options` 键干脆缺席反而能拿到完整的远程搜索。可达性不需要
+任何异常状态:`@object-ui/fields` 的 `deriveFilterFields` 与 `plugin-view` 的
+`deriveFieldOptions` 都把 `options` 原样透传,对象元数据里 picklist 值尚未到位时
+就是这个形状。
+
+objectui#4874(PR #5030)已经为「静态选项集是否真的在位」建了唯一判据
+`hasStaticOptionDomain(field)`(= `options` 是**非空数组**),并按「`options: []`
+属于远程/未到位」这一侧裁定了值域行为。这条分支条件把同一个问题又答了一遍,两个答案
+对 `options: []` 相反:值域侧当它是远程列(保值),控件侧当它是静态列(画空 Select)。
+
+按 2026-08-17 维护者裁定,分支条件改读同一个判据:
+
+- `referenceTo`(或 `type` 为 `user` / `owner`)且 `options` 为 `[]` 的 lookup 列
+  → `LookupValuePicker`,与 `options` 键缺席时完全一致:有搜索框、有候选、能选出
+  新值;多值算子走 picker 的多选形态,仍然回吐列表(objectui#3958)。
+- `options` **非空**的列不受影响 —— 选项集就是它的全部值域,静态 Select 依旧。
+- 分支的其余条件未动:没有 `referenceTo` 又不是 `user` / `owner` 的列(无处可搜)、
+  以及 `select` 这类非 lookup 列,路由与此前逐字相同。
+
+「值必须可见」这一条不变,只是由 picker 而不是临时 `SelectItem` 兑现。
@@ -0,0 +1,327 @@
+/**
+ * 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.
+ */
+
+/**
+ * A lookup column whose `options` are an EMPTY array must still be FILTERABLE
+ * (objectui#5031).
+ *
+ * objectui#4874 (PR #5030) answered the VALUE-DOMAIN question for this shape:
+ * `options: []` means "the static domain is not in place", so a value on such a
+ * column is never cleared against it, and the criterion was written down once,
+ * as `hasStaticOptionDomain(field)` (= `options` is a NON-EMPTY array). But
+ * `renderValueInput`'s remote-picker branch was still asking the same question
+ * in its own words — `!field?.options` — and `[]` is truthy, so it answered the
+ * opposite way: the value-domain side treated the column as remote (keep the
+ * value) while the control side treated it as static (draw the option-driven
+ * Select over zero options).
+ *
+ * The user-visible result was a column that could not be filtered at all: a
+ * scalar operator drew a Select with no candidates and no search box, and
+ * `in`/`notIn` drew an empty checkbox list — while the SAME column with the
+ * `options` key simply absent got full remote search. The two branches now read
+ * one criterion, so a `referenceTo` column with `options: []` reaches
+ * {@link LookupValuePicker}.
+ *
+ * DIRECTIONS, predicted before running (reverse verification restores
+ * `!field?.options` in the branch condition and re-runs this file):
+ *
+ *   - "routes an unloaded lookup column to the remote picker" — RED without the
+ *     fix. Every case there asserts a picker artifact (the search box, the
+ *     candidate list, the by-hand id input, the multi-value id input); on the
+ *     old condition the column draws a Radix Select or a checkbox list instead
+ *     and none of those artifacts exists;
+ *   - "a column that owns its option domain keeps the static Select" — GREEN in
+ *     both directions by design. It is the blast-radius guard: a fix that read
+ *     the criterion inverted, or that sent every lookup to the remote picker,
+ *     turns all of it red;
+ *   - "the branch's other conditions are untouched" — GREEN in both directions
+ *     too. `hasStaticOptionDomain` replaces ONE conjunct; a column with no
+ *     `referenceTo` and a non-lookup type must route exactly as before, or the
+ *     change widened the branch instead of correcting it.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { SchemaRendererContext } from '@object-ui/react';
+import { FilterBuilder } from '../custom/filter-builder';
+
+/**
+ * The columns this card distinguishes. Every one of them is the SAME lookup
+ * apart from its `options` key, because that key is the whole subject:
+ *
+ *   - `account` — `referenceTo`, `options` ABSENT. The shape that already
+ *     reached the remote picker; here as the reference behaviour the others
+ *     are measured against;
+ *   - `account_pending` — `referenceTo`, `options: []`. The card's column: the
+ *     shape `deriveFilterFields` produces before an object's picklist values
+ *     arrive, and the one that used to fall through to an empty Select;
+ *   - `account_loaded` — `referenceTo` AND a NON-EMPTY `options`. A lookup whose
+ *     domain really is local and complete; it must keep the static Select, or
+ *     the fix has taken the static case with it;
+ *   - `owner_pending` — `type: 'owner'` with `options: []` and no `referenceTo`,
+ *     reached through the branch's `type === "owner"` conjunct;
+ *   - `stage_pending` — a `select` (NOT lookup-like) with `options: []`. It has
+ *     no remote search to fall back to, so it must be unaffected;
+ *   - `orphan_pending` — a lookup with `options: []` and NO `referenceTo`, of a
+ *     type that is neither `user` nor `owner`. There is nothing to search
+ *     against, so the branch's third conjunct must keep rejecting it.
+ */
+const FIELDS = [
+  { value: 'title', label: 'Title', type: 'text' },
+  { value: 'account', label: 'Account', type: 'lookup', referenceTo: 'accounts' },
+  {
+    value: 'account_pending',
+    label: 'Account (pending)',
+    type: 'lookup',
+    referenceTo: 'accounts',
+    options: [],
+  },
+  {
+    value: 'account_loaded',
+    label: 'Account (loaded)',
+    type: 'lookup',
+    referenceTo: 'accounts',
+    options: [
+      { value: 'acc_001', label: 'Acme' },
+      { value: 'acc_002', label: 'Globex' },
+    ],
+  },
+  { value: 'owner_pending', label: 'Owner', type: 'owner', options: [] },
+  { value: 'stage_pending', label: 'Stage', type: 'select', options: [] },
+  { value: 'orphan_pending', label: 'Orphan', type: 'lookup', options: [] },
+];
+
+/** The records the remote search returns — the candidates the card says are missing. */
+const ACCOUNTS = [
+  { id: 'acc_007', name: 'Initech' },
+  { id: 'acc_008', name: 'Umbrella' },
+];
+
+function renderRow(
+  condition: Record<string, unknown>,
+  opts: { dataSource?: unknown } = {},
+) {
+  const onChange = vi.fn();
+  // Hoisted OUT of the JSX, as in PR #5030's suite: the sync effect re-seeds
+  // internal state whenever the `value` PROP's identity changes, which would
+  // undo the interaction under test on the next render.
+  const value = { id: 'root', logic: 'and', conditions: [{ id: 'c1', ...condition }] };
+  const tree = (
+    <FilterBuilder fields={FIELDS as any} value={value as any} onChange={onChange} />
+  );
+  const utils = render(
+    opts.dataSource ? (
+      <SchemaRendererContext.Provider value={{ dataSource: opts.dataSource } as any}>
+        {tree}
+      </SchemaRendererContext.Provider>
+    ) : (
+      tree
+    ),
+  );
+  return { ...utils, onChange };
+}
+
+/** A DataSource that answers `find` with {@link ACCOUNTS}. */
+function fakeDataSource() {
+  return { find: vi.fn(async () => ({ data: ACCOUNTS })) };
+}
+
+/**
+ * The row's value control, identified by what it IS rather than by position.
+ *
+ * The bug and the fix draw two structurally different controls, so the pins read
+ * the DOM for the control that is actually there: `comboboxes` counts the Radix
+ * triggers (field, operator, and — only for an option-driven column — value),
+ * and the picker helpers look for `LookupValuePicker`'s own artifacts.
+ */
+function comboboxCount(): number {
+  return screen.queryAllByRole('combobox').length;
+}
+
+function lastRow(onChange: ReturnType<typeof vi.fn>) {
+  const calls = onChange.mock.calls;
+  expect(calls.length, 'the builder never called onChange').toBeGreaterThan(0);
+  return calls[calls.length - 1][0].conditions[0];
+}
+
+describe('routes an unloaded lookup column to the remote picker', () => {
+  it('opens a search box and real candidates for a `referenceTo` column with `options: []`', async () => {
+    const dataSource = fakeDataSource();
+    renderRow(
+      { field: 'account_pending', operator: 'equals', value: '' },
+      { dataSource },
+    );
+
+    // The card's literal complaint, asserted as the user meets it: a trigger
+    // that opens a searchable list. On the old condition this column drew a
+    // Radix Select whose only content was the row's own value.
+    const trigger = screen.getByTestId('lookup-picker-account_pending');
+    fireEvent.click(trigger);
+
+    expect(await screen.findByTestId('lookup-search-account_pending')).toBeInTheDocument();
+    await waitFor(() => {
+      expect(screen.getByText('Initech')).toBeInTheDocument();
+      expect(screen.getByText('Umbrella')).toBeInTheDocument();
+    });
+    expect(dataSource.find).toHaveBeenCalledWith('accounts', expect.anything());
+  });
+
+  it('lets the user pick a NEW value there — the thing the empty Select made impossible', async () => {
+    const dataSource = fakeDataSource();
+    const { onChange } = renderRow(
+      { field: 'account_pending', operator: 'equals', value: '' },
+      { dataSource },
+    );
+
+    fireEvent.click(screen.getByTestId('lookup-picker-account_pending'));
+    const candidate = await screen.findByText('Umbrella');
+    fireEvent.click(candidate);
+
+    // "值可见了,用户依然挑不出别的记录" is what the card is about; this is the
+    // assertion that the user CAN now, and that the choice reaches the row.
+    expect(lastRow(onChange)).toMatchObject({
+      field: 'account_pending',
+      value: 'acc_008',
+    });
+  });
+
+  it('draws no option-driven value Select for that column at all', () => {
+    renderRow({ field: 'account_pending', operator: 'equals', value: 'acc_007' });
+
+    // Field and operator only. A third combobox is the empty Select of the bug
+    // report — the control with no search box and no candidates.
+    expect(comboboxCount()).toBe(2);
+  });
+
+  it('keeps the row value visible in the picker when no DataSource is configured', () => {
+    const { onChange } = renderRow({
+      field: 'account_pending',
+      operator: 'equals',
+      value: 'acc_007',
+    });
+
+    // `LookupValuePicker`'s by-hand fallback. The C half of objectui#4874's
+    // ruling — the value is never invisible — is preserved by the reroute, it
+    // is just the picker that honours it now instead of a temporary SelectItem.
+    const input = document.querySelector<HTMLInputElement>(
+      'input[placeholder="Enter Account (pending) id"]',
+    );
+    expect(input, 'the unloaded lookup drew no id input').toBeTruthy();
+    expect(input!.value).toBe('acc_007');
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('gives the list operators the multi-value picker, not an empty checkbox list', () => {
+    renderRow({ field: 'account_pending', operator: 'in', value: ['acc_007'] });
+
+    // `in`/`notIn` on this column used to render a checkbox list over zero
+    // options: every existing term invisible, no term addable. The multiple
+    // picker keeps list ARITY (objectui#3958) while restoring the search.
+    expect(screen.getByTestId('lookup-ids-account_pending')).toBeInTheDocument();
+    expect(screen.queryAllByRole('checkbox')).toHaveLength(0);
+  });
+
+  it('routes an `owner` column with `options: []` through the same criterion', () => {
+    renderRow({ field: 'owner_pending', operator: 'equals', value: 'usr_1' });
+
+    // The branch's `type === "owner"` conjunct, which supplies its own
+    // `referenceTo` ("users") downstream. `options: []` used to block it here
+    // exactly as it blocked the `referenceTo` case.
+    expect(comboboxCount()).toBe(2);
+    const input = document.querySelector<HTMLInputElement>('input[placeholder="Enter Owner id"]');
+    expect(input, 'the owner column drew no id input').toBeTruthy();
+    expect(input!.value).toBe('usr_1');
+  });
+
+  it('matches the behaviour of the same column with `options` absent', () => {
+    const absent = renderRow({ field: 'account', operator: 'equals', value: 'acc_007' });
+    const absentComboboxes = absent.container.querySelectorAll('[role="combobox"]').length;
+    const absentIdInput = absent.container.querySelector<HTMLInputElement>(
+      'input[placeholder="Enter Account id"]',
+    );
+
+    const pending = renderRow({
+      field: 'account_pending',
+      operator: 'equals',
+      value: 'acc_007',
+    });
+    const pendingComboboxes = pending.container.querySelectorAll('[role="combobox"]').length;
+    const pendingIdInput = pending.container.querySelector<HTMLInputElement>(
+      'input[placeholder="Enter Account (pending) id"]',
+    );
+
+    // The card's own framing: `options: []` and no `options` key describe the
+    // same state of the world (the domain has not arrived), so the column must
+    // not be filterable in one spelling and unfilterable in the other. Compared
+    // control-for-control rather than asserted twice, so the pin fails if either
+    // side moves.
+    expect(pendingComboboxes).toBe(absentComboboxes);
+    expect(absentIdInput?.value).toBe('acc_007');
+    expect(pendingIdInput?.value).toBe('acc_007');
+  });
+});
+
+describe('a column that owns its option domain keeps the static Select', () => {
+  it('draws the option-driven Select for a lookup with NON-EMPTY options', async () => {
+    renderRow({ field: 'account_loaded', operator: 'equals', value: 'acc_001' });
+
+    // The half of the criterion that must NOT move: these options ARE the
+    // column's domain, so the local Select is the right control and the remote
+    // picker would be a regression.
+    expect(comboboxCount()).toBe(3);
+    expect(screen.queryByTestId('lookup-picker-account_loaded')).toBeNull();
+
+    const trigger = screen.getAllByRole('combobox')[2];
+    expect(trigger.textContent).toBe('Acme');
+
+    fireEvent.keyDown(trigger, { key: 'ArrowDown' });
+    await waitFor(() => {
+      expect(
+        screen.getAllByRole('option').map((o) => o.textContent),
+      ).toEqual(expect.arrayContaining(['Acme', 'Globex']));
+    });
+  });
+
+  it('keeps the checkbox list for a list operator on that column', () => {
+    renderRow({ field: 'account_loaded', operator: 'in', value: ['acc_001'] });
+
+    expect(screen.queryByTestId('lookup-ids-account_loaded')).toBeNull();
+    expect(
+      screen.getAllByRole('checkbox').map((box) => ({
+        label: box.parentElement?.textContent ?? '',
+        checked: box.getAttribute('data-state') === 'checked',
+      })),
+    ).toEqual([
+      { label: 'Acme', checked: true },
+      { label: 'Globex', checked: false },
+    ]);
+  });
+});
+
+describe("the branch's other conditions are untouched", () => {
+  it('leaves a non-lookup `select` column with `options: []` exactly where it was', () => {
+    renderRow({ field: 'stage_pending', operator: 'equals', value: 'draft' });
+
+    // `select` is not lookup-like: there is no remote search behind it, so its
+    // empty Select is a metadata problem rather than this defect. Rerouting it
+    // would be the fix over-reaching past the conjunct it replaced.
+    expect(comboboxCount()).toBe(3);
+    expect(screen.queryByTestId('lookup-picker-stage_pending')).toBeNull();
+  });
+
+  it('still rejects a lookup with `options: []` that has nothing to search against', () => {
+    renderRow({ field: 'orphan_pending', operator: 'equals', value: 'x_1' });
+
+    // No `referenceTo`, and neither `user` nor `owner`: the picker would have no
+    // object to query. The third conjunct is what says so, and it is unchanged —
+    // this column's degradation is the card's adjacent observation, out of scope.
+    expect(screen.queryByTestId('lookup-picker-orphan_pending')).toBeNull();
+    expect(comboboxCount()).toBe(3);
+  });
+});