@nocobase/client-v2 2.1.0-beta.36 → 2.1.0-beta.38

package/src/components/form/filter/__tests__/FilterValueInput.test.tsx

@@ -0,0 +1,243 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { FilterValueInput } from '../FilterValueInput';
+import type { FilterOperator, FilterOption } from '../../../../flow/components/filter/useFilterOptions';
+
+type Case = {
+  /** Human-readable description of the v1 interface this case mirrors. */
+  name: string;
+  /** Field uiSchema. Operator schema is optional and overrides this. */
+  fieldComponent?: string;
+  fieldEnum?: any[];
+  operator?: FilterOperator;
+  /** Selector used to confirm the right antd control rendered. */
+  selector: string;
+  /** Optional: drive an interaction and assert onChange payload. */
+  interact?: (container: HTMLElement, onChange: ReturnType<typeof vi.fn>) => void;
+  expectedOnChange?: any;
+};
+
+const fieldOf = (component: string, extra: Partial<FilterOption['schema']> = {}): FilterOption => ({
+  name: 'f',
+  title: 'F',
+  schema: { 'x-component': component, ...extra },
+});
+
+const opOf = (overrides: Partial<FilterOperator> = {}): FilterOperator => ({
+  value: '$eq',
+  label: 'is',
+  ...overrides,
+});
+
+// One row per v1 field interface → expected v2 antd control. Detection is kept to a single CSS selector per case so the table reads as "interface ↔ selector"; interactive assertions are added only where the value-onChange contract is non-trivial (e.g. Checkbox.target.checked, ColorPicker hex extraction).
+const CASES: Case[] = [
+  // string / email / phone / uuid / nanoid / url all default to Input
+  { name: 'input → antd Input', fieldComponent: 'Input', selector: 'input[type="text"]' },
+  { name: 'Input.URL → antd Input', fieldComponent: 'Input.URL', selector: 'input[type="text"]' },
+  { name: 'NanoIDInput → antd Input', fieldComponent: 'NanoIDInput', selector: 'input[type="text"]' },
+
+  // textarea / markdown / richText / json all collapse to TextArea
+  { name: 'textarea → antd Input.TextArea', fieldComponent: 'Input.TextArea', selector: 'textarea' },
+  { name: 'markdown → antd Input.TextArea', fieldComponent: 'Markdown', selector: 'textarea' },
+  { name: 'richText → antd Input.TextArea', fieldComponent: 'RichText', selector: 'textarea' },
+  { name: 'json → antd Input.TextArea', fieldComponent: 'Input.JSON', selector: 'textarea' },
+
+  // numeric inputs
+  { name: 'integer → antd InputNumber', fieldComponent: 'InputNumber', selector: '.ant-input-number' },
+  { name: 'percent → antd InputNumber', fieldComponent: 'Percent', selector: '.ant-input-number' },
+
+  // password — the case that prompted this audit
+  {
+    name: 'password → PasswordInput (Input.Password)',
+    fieldComponent: 'Password',
+    selector: 'input[type="password"]',
+  },
+
+  // pickers
+  {
+    name: 'datetime field → antd DatePicker (no operator override)',
+    fieldComponent: 'DatePicker',
+    selector: '.ant-picker',
+  },
+  { name: 'unixTimestamp → antd DatePicker', fieldComponent: 'UnixTimestamp', selector: '.ant-picker' },
+  { name: 'time → antd TimePicker', fieldComponent: 'TimePicker', selector: '.ant-picker' },
+  { name: 'color → antd ColorPicker', fieldComponent: 'ColorPicker', selector: '.ant-color-picker-trigger' },
+
+  // boolean / single-choice / multi-choice
+  { name: 'checkbox → antd Checkbox', fieldComponent: 'Checkbox', selector: 'input[type="checkbox"]' },
+  {
+    name: 'checkboxGroup with field enum → antd Checkbox.Group',
+    fieldComponent: 'Checkbox.Group',
+    fieldEnum: [
+      { label: 'A', value: 'a' },
+      { label: 'B', value: 'b' },
+    ],
+    selector: '.ant-checkbox-group',
+  },
+  {
+    name: 'radioGroup with field enum → antd Radio.Group',
+    fieldComponent: 'Radio.Group',
+    fieldEnum: [
+      { label: 'A', value: 'a' },
+      { label: 'B', value: 'b' },
+    ],
+    selector: '.ant-radio-group',
+  },
+  { name: 'select → antd Select', fieldComponent: 'Select', selector: '.ant-select' },
+
+  // operator-level overrides — datetime operator schema wins over field uiSchema
+  {
+    name: '$dateOn operator → smart date picker',
+    fieldComponent: 'DatePicker',
+    operator: opOf({
+      schema: { 'x-component': 'DateFilterDynamicComponent', 'x-component-props': { isRange: false } },
+    }),
+    selector: '.ant-picker',
+  },
+  {
+    name: '$anyOf array operator → Select with tags mode',
+    fieldComponent: 'Input',
+    operator: opOf({
+      value: '$anyOf',
+      schema: { 'x-component': 'Select', 'x-component-props': { mode: 'tags' } },
+    }),
+    selector: '.ant-select-selection-overflow',
+  },
+
+  // noValue operators render nothing
+  {
+    name: '$empty operator → renders nothing',
+    fieldComponent: 'Input',
+    operator: opOf({ value: '$empty', noValue: true }),
+    selector: '*',
+    // selector intentionally generic; we assert empty container via interact
+  },
+];
+
+function setup(c: Case) {
+  const onChange = vi.fn();
+  const field = c.fieldComponent
+    ? fieldOf(c.fieldComponent, c.fieldEnum ? ({ enum: c.fieldEnum } as any) : {})
+    : undefined;
+  const utils = render(<FilterValueInput field={field} operator={c.operator} value={undefined} onChange={onChange} />);
+  return { onChange, ...utils };
+}
+
+describe('FilterValueInput dispatch table', () => {
+  for (const c of CASES) {
+    it(c.name, () => {
+      const { container } = setup(c);
+      if (c.operator?.noValue) {
+        // For noValue operators the component returns null.
+        expect(
+          container.querySelector('input, textarea, .ant-select, .ant-picker, .ant-color-picker-trigger'),
+        ).toBeNull();
+        return;
+      }
+      expect(container.querySelector(c.selector)).not.toBeNull();
+    });
+  }
+});
+
+describe('FilterValueInput interaction wiring', () => {
+  // Spot-check a handful of write-through paths that have non-trivial event shapes (target.checked, event vs raw value, hex extraction from ColorPicker).
+  it('Checkbox emits the boolean from target.checked', () => {
+    const onChange = vi.fn();
+    const { container } = render(
+      <FilterValueInput field={fieldOf('Checkbox')} operator={opOf()} value={false} onChange={onChange} />,
+    );
+    fireEvent.click(container.querySelector('input[type="checkbox"]') as HTMLInputElement);
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+
+  it('Password emits the unwrapped string from the input event', () => {
+    const onChange = vi.fn();
+    const { container } = render(
+      <FilterValueInput field={fieldOf('Password')} operator={opOf()} value="" onChange={onChange} />,
+    );
+    const input = container.querySelector('input[type="password"]') as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'hunter2' } });
+    expect(onChange).toHaveBeenCalledWith('hunter2');
+  });
+
+  it('TextArea emits the unwrapped string', () => {
+    const onChange = vi.fn();
+    const { container } = render(
+      <FilterValueInput field={fieldOf('Input.TextArea')} operator={opOf()} value="" onChange={onChange} />,
+    );
+    fireEvent.change(container.querySelector('textarea') as HTMLTextAreaElement, {
+      target: { value: 'abuse' },
+    });
+    expect(onChange).toHaveBeenCalledWith('abuse');
+  });
+
+  it('Radio.Group emits the picked value (not the event)', () => {
+    const onChange = vi.fn();
+    const { container } = render(
+      <FilterValueInput
+        field={fieldOf('Radio.Group', {
+          enum: [
+            { label: 'A', value: 'a' },
+            { label: 'B', value: 'b' },
+          ],
+        } as any)}
+        operator={opOf()}
+        value={undefined}
+        onChange={onChange}
+      />,
+    );
+    fireEvent.click(container.querySelectorAll('input[type="radio"]')[1] as HTMLInputElement);
+    expect(onChange).toHaveBeenCalledWith('b');
+  });
+
+  it('Fallback Input honours the placeholder prop', () => {
+    render(<FilterValueInput operator={opOf()} value="" onChange={() => undefined} placeholder="Enter value" />);
+    expect(screen.getByPlaceholderText('Enter value')).toBeInTheDocument();
+  });
+});
+
+describe('FilterValueInput schema precedence', () => {
+  it('operator schema wins over field uiSchema', () => {
+    // Field would render Input, but operator forces Select.
+    render(
+      <FilterValueInput
+        field={fieldOf('Input')}
+        operator={opOf({
+          schema: { 'x-component': 'Select', 'x-component-props': { mode: 'tags' } },
+        })}
+        value={[]}
+        onChange={() => undefined}
+      />,
+    );
+    expect(document.querySelector('.ant-select')).not.toBeNull();
+  });
+
+  it('field uiSchema is used when operator has none', () => {
+    const { container } = render(
+      <FilterValueInput
+        field={fieldOf('InputNumber')}
+        operator={opOf()}
+        value={undefined}
+        onChange={() => undefined}
+      />,
+    );
+    expect(container.querySelector('.ant-input-number')).not.toBeNull();
+  });
+
+  it('plain Input is used when neither side has a schema', () => {
+    const { container } = render(
+      <FilterValueInput operator={opOf()} value="" onChange={() => undefined} placeholder="x" />,
+    );
+    expect(container.querySelector('input[type="text"]')).not.toBeNull();
+  });
+});

package/src/components/form/filter/__tests__/compileFilterGroup.test.ts

@@ -0,0 +1,146 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { compileFilterGroup } from '../useFilterActionProps';
+
+describe('compileFilterGroup', () => {
+  it('returns undefined for an empty group so callers can drop the filter param', () => {
+    expect(compileFilterGroup(undefined)).toBeUndefined();
+    expect(compileFilterGroup({ logic: '$and', items: [] })).toBeUndefined();
+  });
+
+  it('compiles a single condition into the NocoBase {path: {op: val}} envelope', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [{ path: 'lockReason', operator: '$includes', value: 'abuse' }],
+    });
+    expect(out).toEqual({ $and: [{ lockReason: { $includes: 'abuse' } }] });
+  });
+
+  it('preserves the parent logic ($and / $or)', () => {
+    const out = compileFilterGroup({
+      logic: '$or',
+      items: [
+        { path: 'lockReason', operator: '$eq', value: 'abuse' },
+        { path: 'lockReason', operator: '$eq', value: 'spam' },
+      ],
+    });
+    expect(out).toEqual({
+      $or: [{ lockReason: { $eq: 'abuse' } }, { lockReason: { $eq: 'spam' } }],
+    });
+  });
+
+  it('compiles nested groups recursively', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: 'lockReason', operator: '$eq', value: 'abuse' },
+        {
+          logic: '$or',
+          items: [
+            { path: 'lockedTs', operator: '$dateAfter', value: '2026-01-01' },
+            { path: 'lockedTs', operator: '$dateBefore', value: '2026-12-31' },
+          ],
+        },
+      ],
+    });
+    expect(out).toEqual({
+      $and: [
+        { lockReason: { $eq: 'abuse' } },
+        {
+          $or: [{ lockedTs: { $dateAfter: '2026-01-01' } }, { lockedTs: { $dateBefore: '2026-12-31' } }],
+        },
+      ],
+    });
+  });
+
+  it('drops items with empty values (undefined / "" / [] / {}) so half-edited rows do not 500 the server', () => {
+    // Mirrors v1's `removeNullCondition` behaviour. A user who selected a field + operator but hasn't typed a value yet must NOT cause `{path:{operator:undefined}}` to fly out — the server rejects empty operator bodies on `$dateOn` etc.
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: 'lockedTs', operator: '$dateOn', value: undefined },
+        { path: 'lockReason', operator: '$eq', value: '' },
+        { path: 'lockReason', operator: '$in', value: [] },
+        { path: 'lockedTs', operator: '$dateOn', value: {} },
+        { path: 'lockReason', operator: '$eq', value: 'kept' },
+      ],
+    });
+    expect(out).toEqual({ $and: [{ lockReason: { $eq: 'kept' } }] });
+  });
+
+  it('expands dotted association paths into nested objects (matches v1 payload shape)', () => {
+    // `user.createdBy.password` must reach the server as a nested object so the filter resolver walks the association chain. Flattened-key form (`{ "user.createdBy.password": ... }`) leaves the server treating the whole string as one column name.
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [{ path: 'user.createdBy.password', operator: '$includes', value: '123' }],
+    });
+    expect(out).toEqual({
+      $and: [{ user: { createdBy: { password: { $includes: '123' } } } }],
+    });
+  });
+
+  it('keeps relative date descriptors (non-empty plain objects) intact', () => {
+    // `{ type: 'today' }` is an empty-keys-only check away from being pruned by accident. Confirm it survives — that's the server-readable shape for relative-date filters.
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [{ path: 'lockedTs', operator: '$dateOn', value: { type: 'today' } }],
+    });
+    expect(out).toEqual({ $and: [{ lockedTs: { $dateOn: { type: 'today' } } }] });
+  });
+
+  it('drops items missing path or operator so half-typed rows do not break the query', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: '', operator: '$eq', value: 'orphan' },
+        { path: 'lockReason', operator: '', value: 'orphan' },
+        { path: 'lockReason', operator: '$eq', value: 'kept' },
+      ],
+    });
+    expect(out).toEqual({ $and: [{ lockReason: { $eq: 'kept' } }] });
+  });
+
+  it('drops empty nested groups so a half-built sub-group does not produce { $or: [] }', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: 'lockReason', operator: '$eq', value: 'abuse' },
+        { logic: '$or', items: [] },
+      ],
+    });
+    expect(out).toEqual({ $and: [{ lockReason: { $eq: 'abuse' } }] });
+  });
+
+  it('returns undefined when every item drops out', () => {
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: '', operator: '', value: '' },
+        { logic: '$or', items: [] },
+      ],
+    });
+    expect(out).toBeUndefined();
+  });
+
+  it('passes complex value shapes (date descriptors, arrays) through unchanged', () => {
+    const dateDescriptor = { type: 'past', number: 3, unit: 'day' };
+    const out = compileFilterGroup({
+      logic: '$and',
+      items: [
+        { path: 'lockedTs', operator: '$dateOn', value: dateDescriptor },
+        { path: 'lockReason', operator: '$in', value: ['abuse', 'spam'] },
+      ],
+    });
+    expect(out).toEqual({
+      $and: [{ lockedTs: { $dateOn: dateDescriptor } }, { lockReason: { $in: ['abuse', 'spam'] } }],
+    });
+  });
+});

package/src/components/form/filter/index.ts

@@ -0,0 +1,13 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+// Higher-level filter compositions for non-schema surfaces (settings pages, panels, side drawers). The low-level primitives — `FilterContainer`, `FilterGroup`, `FilterItem`, `fieldsToOptions`, `useFilterOptions` — live under `src/flow/components/filter/`; this layer composes them with a `Collection` binding and exposes the hook/component pair callers actually reach for. The dependency direction is form/filter → flow/components/filter only.
+export { CollectionFilter } from './CollectionFilter';
+export type { CollectionFilterProps } from './CollectionFilter';
+export type { CompiledFilter } from './useFilterActionProps';

package/src/components/form/filter/useFilterActionProps.ts

@@ -0,0 +1,200 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { Collection, observable } from '@nocobase/flow-engine';
+import { useMemoizedFn } from 'ahooks';
+import { useMemo, useRef } from 'react';
+import { FilterOption, useFilterOptions, UseFilterOptionsArgs } from '../../../flow/components/filter/useFilterOptions';
+import { CollectionFilterItemValue, createCollectionFilterItem } from './CollectionFilterItem';
+
+/** A single condition row (`{ path, operator, value }`) or a nested group. */
+export type FilterGroupItem = CollectionFilterItemValue | FilterGroupValue;
+
+/**
+ * Reactive shape consumed by `FilterContainer` / `FilterGroup`. `logic` is the join (`$and` / `$or`) and `items` is a heterogeneous list of leaf conditions and nested groups.
+ */
+export type FilterGroupValue = {
+  logic: '$and' | '$or';
+  items: FilterGroupItem[];
+};
+
+/** Compiled filter param accepted by NocoBase resource `list`. */
+export type CompiledFilter = Record<string, unknown> | undefined;
+
+interface FilterCtxModel {
+  translate: (key: string) => string;
+  dispatchEvent: (event: 'submit' | 'reset' | (string & {})) => void;
+}
+
+export interface FilterCtx {
+  model: FilterCtxModel;
+}
+
+const isGroup = (item: FilterGroupItem): item is FilterGroupValue =>
+  Array.isArray((item as FilterGroupValue).items) && typeof (item as FilterGroupValue).logic === 'string';
+
+const isCondition = (item: FilterGroupItem): item is CollectionFilterItemValue =>
+  typeof (item as CollectionFilterItemValue).path === 'string' &&
+  Object.prototype.hasOwnProperty.call(item, 'operator');
+
+/**
+ * `true` when the rhs of a condition is "no real value yet" — covers `undefined` / `null` / empty string / empty array / empty plain object. Mirrors v1's `removeNullCondition` `isEmpty` predicate so half-filled rows ("Locked time → is → (no date picked yet)") get dropped on Submit instead of being sent to the server as `{lockedTs:{}}` and triggering a 500.
+ */
+const isEmptyFilterValue = (value: unknown): boolean => {
+  if (value === undefined || value === null || value === '') return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === 'object') {
+    // Plain `{}` only — descriptor shapes like `{ type: 'today' }` have own keys and survive this check.
+    return Object.keys(value as Record<string, unknown>).length === 0;
+  }
+  return false;
+};
+
+/**
+ * Build a nested object from a dotted path. `'user.createdBy.password'` + `{ $includes: '123' }` becomes `{ user: { createdBy: { password: { $includes: '123' } } } }`. Matches v1's filter payload shape so server-side filter resolution sees the same association chain whether the request came from a v1 or v2 page.
+ */
+const nestPath = (path: string, leaf: unknown): Record<string, unknown> => {
+  const segments = path.split('.');
+  let result: unknown = leaf;
+  for (let i = segments.length - 1; i >= 0; i--) {
+    result = { [segments[i]]: result };
+  }
+  return result as Record<string, unknown>;
+};
+
+/**
+ * Compile a reactive filter group into the `{ $and: [{ path: { op: val } }] }` envelope accepted by NocoBase's resource `list` filter param. Returns `undefined` when the group is empty so callers can drop the param.
+ *
+ * Mirrors v1's `removeNullCondition` + filter compile path, but works on the v2 `{ logic, items }` group structure rather than v1's Formily-bracketed `$and.0.path.$eq` shape:
+ *
+ * - Rows missing `path` or `operator` are dropped (still mid-edit).
+ * - Rows whose `value` is empty (`undefined`, `''`, `[]`, `{}`) are dropped — matches v1, which sends `filter={}` for a row with only a field/operator picked. Sending `{lockedTs:{}}` would 500.
+ * - Dotted association paths (`user.createdBy.password`) are expanded into nested objects — matches v1's payload shape, which the server resolves along the association chain rather than treating the dotted string as a single key.
+ * - Empty groups (after pruning) propagate as `undefined` so the outermost caller can drop the whole `filter` param.
+ */
+export function compileFilterGroup(group: FilterGroupValue | undefined): CompiledFilter {
+  if (!group?.items?.length) return undefined;
+  const compiled = group.items
+    .map((entry) => {
+      if (isGroup(entry)) return compileFilterGroup(entry);
+      if (!isCondition(entry) || !entry.path || !entry.operator) return undefined;
+      if (isEmptyFilterValue(entry.value)) return undefined;
+      return nestPath(entry.path, { [entry.operator]: entry.value });
+    })
+    .filter((v): v is Record<string, unknown> => !!v);
+  if (!compiled.length) return undefined;
+  return { [group.logic]: compiled };
+}
+
+const createEmptyGroup = (): FilterGroupValue => ({ logic: '$and', items: [] });
+
+/** Which footer button triggered the apply — useful for closing a popover on Submit but keeping it open on Reset. */
+export type FilterApplyAction = 'submit' | 'reset';
+
+export interface UseFilterActionPropsArgs extends UseFilterOptionsArgs {
+  /** Collection whose fields populate the filter row's field picker. */
+  collection: Collection | undefined;
+  /**
+   * Called when the user submits or resets the filter popover. Receives the compiled filter param (`undefined` when cleared) and which footer button triggered the call. Typical implementation: `(filter, action) => { listRequest.run(filter); if (action === 'submit') closePopover(); }`.
+   */
+  onApply: (filter: CompiledFilter, action: FilterApplyAction) => void;
+}
+
+export interface UseFilterActionPropsResult {
+  /**
+   * Reactive filter group state. Pass directly to `<FilterContent value={...}>`. Stable across renders.
+   */
+  value: FilterGroupValue;
+  /** Field-option tree (for inspection or custom badges). */
+  options: FilterOption[];
+  /** Bound `FilterItem` component to plug into `<FilterContent FilterItem={...}>`. */
+  FilterItem: ReturnType<typeof createCollectionFilterItem> | undefined;
+  /**
+   * Ready-to-use `ctx` for `<FilterContent ctx={...}>`. Wires Submit / Reset buttons to `onSubmit` / `onReset` below.
+   */
+  ctx: FilterCtx;
+  /** Imperative trigger — submit current group as a compiled filter. */
+  onSubmit: () => void;
+  /** Imperative trigger — clear the group and emit an empty filter. */
+  onReset: () => void;
+  /**
+   * Count of top-level condition rows. Useful for showing a badge like `Filter (3)` on the trigger button — matches v1's `field.title = t('{{count}} filter items', { count })`.
+   */
+  conditionCount: number;
+}
+
+/**
+ * v2 equivalent of v1's `useFilterActionProps` for non-schema surfaces (settings pages, panels, side drawers). Bundles three things v1's hook returned implicitly through schema:
+ *
+ * - A reactive `{ logic, items }` group state that `<FilterContent>` reads.
+ * - A bound `FilterItem` component (driven by `createCollectionFilterItem`).
+ * - A `ctx` object that turns `<FilterContent>`'s `dispatchEvent('submit' | 'reset')` into a compiled filter param passed to `onApply`.
+ *
+ * Pair with antd `Popover` to recreate the legacy `Filter.Action` UX:
+ *
+ * ```tsx
+ * const { value, ctx, FilterItem, onSubmit, conditionCount } = useFilterActionProps({
+ *   collection,
+ *   onApply: (filter) => listRequest.run(filter),
+ *   t,
+ * });
+ * return (
+ *   <Popover content={<FilterContent value={value} ctx={ctx} FilterItem={FilterItem} />}>
+ *     <Button>{t('Filter')}{conditionCount ? ` (${conditionCount})` : ''}</Button>
+ *   </Popover>
+ * );
+ * ```
+ */
+export function useFilterActionProps(args: UseFilterActionPropsArgs): UseFilterActionPropsResult {
+  const { collection, onApply, filterableFieldNames, noIgnore, t } = args;
+
+  // Held in a ref so the group object identity is stable for the lifetime of the host component — `<FilterContent>` mutates this object directly (push/splice on `items`, swap `logic`), and a fresh observable on every render would reset that internal state.
+  const valueRef = useRef<FilterGroupValue>();
+  if (!valueRef.current) {
+    valueRef.current = observable(createEmptyGroup()) as FilterGroupValue;
+  }
+  const value = valueRef.current;
+
+  const options = useFilterOptions(collection, { filterableFieldNames, noIgnore, t });
+
+  const FilterItem = useMemo(
+    () => (collection ? createCollectionFilterItem(collection, { filterableFieldNames, noIgnore, t }) : undefined),
+    [collection, filterableFieldNames, noIgnore, t],
+  );
+
+  const onSubmit = useMemoizedFn(() => {
+    onApply(compileFilterGroup(value), 'submit');
+  });
+
+  const onReset = useMemoizedFn(() => {
+    value.logic = '$and';
+    value.items = [];
+    onApply(undefined, 'reset');
+  });
+
+  const translate = useMemoizedFn((key: string) => (t ? t(key) : key));
+
+  const ctx = useMemo<FilterCtx>(
+    () => ({
+      model: {
+        translate,
+        dispatchEvent: (event: string) => {
+          if (event === 'submit') onSubmit();
+          else if (event === 'reset') onReset();
+        },
+      },
+    }),
+    [translate, onSubmit, onReset],
+  );
+
+  // Re-read on each render so `observer`-wrapped hosts re-render when the reactive `items` array length changes. No useMemo needed — the `value` object's identity is stable (held in a ref), but its observable `items.length` is what we actually care about, and the eslint exhaustive-deps rule rightly complains about depending on a mutable property of a stable ref.
+  const conditionCount = value.items.length;
+
+  return { value, options, FilterItem, ctx, onSubmit, onReset, conditionCount };
+}

package/src/components/form/index.tsx

@@ -8,6 +8,7 @@
  */
 
 export * from './createFormRegistry';
+export * from './filter';
 export * from './DialogFormLayout';
 export * from './DrawerFormLayout';
 export * from './EnvVariableInput';