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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/client-v2",
-  "version": "2.1.0-beta.36",
+  "version": "2.1.0-beta.37",
   "license": "Apache-2.0",
   "main": "lib/index.js",
   "module": "es/index.mjs",
@@ -26,11 +26,11 @@
     "@formily/antd-v5": "1.2.3",
     "@formily/react": "^2.2.27",
     "@formily/shared": "^2.2.27",
-    "@nocobase/evaluators": "2.1.0-beta.36",
-    "@nocobase/flow-engine": "2.1.0-beta.36",
-    "@nocobase/sdk": "2.1.0-beta.36",
-    "@nocobase/shared": "2.1.0-beta.36",
-    "@nocobase/utils": "2.1.0-beta.36",
+    "@nocobase/evaluators": "2.1.0-beta.37",
+    "@nocobase/flow-engine": "2.1.0-beta.37",
+    "@nocobase/sdk": "2.1.0-beta.37",
+    "@nocobase/shared": "2.1.0-beta.37",
+    "@nocobase/utils": "2.1.0-beta.37",
     "ahooks": "^3.7.2",
     "antd": "5.24.2",
     "antd-style": "3.7.1",
@@ -44,5 +44,5 @@
     "react-i18next": "^11.15.1",
     "react-router-dom": "^6.30.1"
   },
-  "gitHead": "397d45c744f6eb48b3a0cd785c87cbf1257c3513"
+  "gitHead": "7132e5b83ecc0e42b54715eaf1429c72bcef34ae"
 }

package/src/BaseApplication.tsx

@@ -169,6 +169,18 @@ export abstract class BaseApplication<
     return this.wsAuthorized;
   }
 
+  public setDocumentLanguage(language?: string | null) {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    if (language) {
+      document.documentElement.lang = language;
+    } else {
+      document.documentElement.removeAttribute('lang');
+    }
+  }
+
   constructor(protected options: TOptions = {} as TOptions) {
     this.initRequireJs();
     this.defineObservableState();
@@ -205,6 +217,7 @@ export abstract class BaseApplication<
     this.addRoutes();
     this.i18n.on('languageChanged', (lng) => {
       this.apiClient.auth.locale = lng;
+      this.setDocumentLanguage(lng);
     });
     this.initListeners();
     this.afterManagersInitialized();

package/src/__tests__/app.test.tsx

@@ -33,6 +33,7 @@ describe('app', () => {
 
     afterEach(() => {
       document.querySelectorAll('link[rel="shortcut icon"]').forEach((node) => node.remove());
+      document.documentElement.removeAttribute('lang');
       vi.restoreAllMocks();
     });
 
@@ -89,6 +90,14 @@ describe('app', () => {
       expect(favicon.getAttribute('href')).toBe('/favicon/favicon.ico');
     });
 
+    it('should sync document language when app language changes', async () => {
+      const app = new Application({ router });
+
+      await app.i18n.changeLanguage('ja-JP');
+
+      expect(document.documentElement.lang).toBe('ja-JP');
+    });
+
     it('should escape app version html placeholder content', () => {
       expect(getAppVersionHTML('<script>alert(1)</script>&"')).toBe(
         '<span class="nb-app-version">v&lt;script&gt;alert(1)&lt;/script&gt;&amp;&quot;</span>',

package/src/components/README.md

@@ -14,9 +14,9 @@ Grouped by purpose: form containers, form fields, data table, utilities.
 
 #### DrawerFormLayout
 
-Drawer-style form layout. Pair with `ctx.viewer.drawer({ content })`.
+Drawer-style form layout. Pair with `ctx.viewer.drawer({ closable: true, content })`.
 
-- Top: a close icon next to the title. Clicking close fires `onCancel` and dismisses the drawer
+- Top: title only; the native close X is rendered by antd Drawer — you must pass `closable: true` on the `viewer.drawer` call for it to appear
 - Bottom: default Cancel / Submit buttons; override the whole footer with `footer`
 - Middle: caller-supplied `<Form>` instance + fields
 
@@ -25,6 +25,7 @@ import { DrawerFormLayout } from '@nocobase/client-v2';
 
 ctx.viewer.drawer({
   width: '50%',
+  closable: true,  // restore antd Drawer's native close X
   content: () => (
     <DrawerFormLayout
       title={t('Add authenticator')}
@@ -41,17 +42,19 @@ ctx.viewer.drawer({
 
 Key props:
 
-- `title`: title node (rendered next to the close icon)
-- `onCancel` / `onSubmit`: callbacks; the drawer closes automatically once they resolve. Throw from `onSubmit` to keep the drawer open (e.g. on a validation error)
+- `title`: title node
+- `onSubmit`: callback; the drawer closes automatically once it resolves. Throw to keep the drawer open (e.g. on a validation error)
 - `submitting`: drives the Submit button's loading state
 - `submitText` / `cancelText`: button labels
 - `footer`: full override of the footer content (replaces the default Cancel + Submit pair)
 
+To intercept close (e.g. dirty-form confirmation), use the lower-level `viewer.drawer({ preventClose, beforeClose })` hooks — this layout no longer wraps a custom cancel handler.
+
 #### DialogFormLayout
 
 Dialog-style form layout, the centered counterpart of `DrawerFormLayout`. Pair with `ctx.viewer.dialog({ closable: true, content })`.
 
-The only visual difference from the drawer version: the title is a bare string (no inline close icon), relying on antd Modal's native top-right X. Note that `viewer.dialog` disables antd's native X by default — you have to pass `closable: true` explicitly for it to appear.
+The only visual difference from the drawer version is where the native close X sits — antd Drawer renders it at the top-left of the title bar, antd Modal at the top-right. Both layouts rely on the caller passing `closable: true` at the viewer call site; neither renders a close icon itself.
 
 ```tsx
 import { DialogFormLayout } from '@nocobase/client-v2';
@@ -73,7 +76,7 @@ When to pick which:
 - **Drawer**: long forms with lots of fields that benefit from a full-height side panel (settings-page "Add / Edit")
 - **Dialog**: short forms that ask for quick confirmation (bind, change password, two-factor verify)
 
-Props are identical to `DrawerFormLayout` — they're drop-in replacements at the API level.
+Props are nearly identical to `DrawerFormLayout`, with one extra: `DialogFormLayout` accepts an `onCancel` callback (fired by both the Cancel button and the native X) for "discard changes" confirmations.
 
 ### Form fields
 
@@ -272,6 +275,48 @@ Companion exports:
 - `PAGE_SIZE_OPTIONS`: suggested page-size dropdown values `[5, 10, 20, 50, 100, 200]`
 - `SortHandle`: standalone handle component, exported from `@nocobase/client-v2` for embedding into custom columns
 
+### Filter
+
+#### CollectionFilter
+
+Filter button bound to a Collection. Clicking opens a Popover hosting a multi-condition filter form (field picker + operator + value control). Submit dismisses the Popover and emits the compiled NocoBase filter via `onChange`; Reset keeps the Popover open and emits `undefined`.
+
+```tsx
+import { CollectionFilter, ExtendCollectionsProvider } from '@nocobase/client-v2';
+import lockedUsersCollection from '../../collections/locked-users';
+
+function Page() {
+  const main = engine.context.dataSourceManager?.getDataSource?.('main');
+  const collection = main?.getCollection?.(lockedUsersCollection.name);
+
+  const listRequest = useRequest(
+    async (filter) => api.resource('lockedUsers').list({ ...(filter ? { filter } : {}) }),
+    { defaultParams: [undefined] },
+  );
+
+  return (
+    <ExtendCollectionsProvider collections={[lockedUsersCollection]}>
+      <CollectionFilter collection={collection} onChange={listRequest.run} t={t} />
+      {/* table … */}
+    </ExtendCollectionsProvider>
+  );
+}
+```
+
+Key props:
+
+- `collection`: the Collection that drives the field picker. The button is disabled while it's `undefined`
+- `onChange: (filter) => void`: fired on Submit and Reset with the compiled NocoBase filter (`undefined` on Reset). Most pages forward straight to `listRequest.run`
+- `t`: translator. Pass `useT()` from a plugin's `locale.ts` so server-side `{{t("…")}}` macros in field / operator labels get expanded — plain react-i18next's `t` leaves them as literal template strings
+- `filterableFieldNames`: whitelist of root-level field names to expose
+- `noIgnore`: bypass the whitelist
+- `buttonText`: override the trigger label; defaults to `t('Filter')`
+- `showCount`: show the `(N)` condition-count badge on the trigger; defaults to `true`
+- `popoverProps` / `buttonProps`: pass-through to the antd `Popover` / `Button`
+- `popoverMinWidth`: min-width of the popover body; defaults to `520`
+
+If the target Collection is `schema-only` (not auto-published from the server to the v2 data source), wrap the page in `<ExtendCollectionsProvider>` so `CollectionFilter` can resolve it by name.
+
 ### Utilities
 
 #### createFormRegistry
@@ -302,6 +347,44 @@ Use this when a plugin needs an extension point for "same name + same shape + di
 
 Re-registering the same `name` overwrites the previous entry and emits a `console.warn` — HMR doesn't throw, and unintended duplicates surface in dev.
 
+## data-source/
+
+Components that wire collections / data sources into the React tree. Exported from the top level of `@nocobase/client-v2`.
+
+### ExtendCollectionsProvider
+
+Mount-scoped collection injector. On mount it registers the given collections into the target data source; on unmount it removes them. A `dataSource:loaded` listener re-applies the registration so mid-session reloads don't wipe injected collections.
+
+```tsx
+import { ExtendCollectionsProvider } from '@nocobase/client-v2';
+import lockedUsersCollection from '../../collections/locked-users';
+
+// Module-level constant — keeps the reference stable so the provider's
+// effect doesn't re-run on every parent re-render.
+const collections = [lockedUsersCollection];
+
+export function LockedUsersPage() {
+  return (
+    <ExtendCollectionsProvider collections={collections}>
+      <LockedUsersPageInner />
+    </ExtendCollectionsProvider>
+  );
+}
+```
+
+Key props:
+
+- `collections: CollectionOptions[]`: collections to inject. The provider only adds names that aren't already present, and on unmount removes only the ones it added
+- `dataSource`: target data source key; defaults to `'main'`
+- `children`: subtree covered by the injection
+
+When to use:
+
+- The server-side collection is `schema-only` and doesn't get auto-published to the client data source (e.g. `lockedUsers`)
+- You need a client-side mirror that should be visible only inside the current page, not registered globally
+
+Typical pairing: use together with `<CollectionFilter>` — the provider makes the collection resolvable; the filter button consumes it.
+
 ## When to add a new component here
 
 - Two or more plugins need the same field or container shape — promote it to this folder

package/src/components/README.zh-CN.md

@@ -14,9 +14,9 @@
 
 #### DrawerFormLayout
 
-抽屉形态的表单 layout。配合 `ctx.viewer.drawer({ content })` 用。
+抽屉形态的表单 layout。配合 `ctx.viewer.drawer({ closable: true, content })` 用。
 
-- 顶部 Header：左上角一个 close 图标 + 标题。点击 close 会触发 `onCancel` 然后关闭抽屉
+- 顶部 Header：只放标题；左侧的关闭 X 来自 antd Drawer——必须在 `viewer.drawer` 上显式传 `closable: true` 才会出现
 - 底部 Footer：默认 Cancel / Submit 两个按钮；可以用 `footer` 完全替换
 - 中间 children：调用方自己放 `<Form>` 实例 + 字段
 
@@ -25,6 +25,7 @@ import { DrawerFormLayout } from '@nocobase/client-v2';
 
 ctx.viewer.drawer({
   width: '50%',
+  closable: true,  // 关键：开启 antd Drawer 原生关闭 X
   content: () => (
     <DrawerFormLayout
       title={t('添加认证器')}
@@ -41,17 +42,19 @@ ctx.viewer.drawer({
 
 主要属性：
 
-- `title`：标题节点（旁边带 close 图标）
-- `onCancel` / `onSubmit`：回调，resolve 后会自动关闭抽屉。Submit 里 throw 可以让抽屉保持打开（比如校验失败）
+- `title`：标题节点
+- `onSubmit`：回调，resolve 后会自动关闭抽屉。throw 可以让抽屉保持打开（比如校验失败）
 - `submitting`：驱动 Submit 按钮的 loading
 - `submitText` / `cancelText`：按钮文字
 - `footer`：完全自定义 Footer 内容（覆盖默认两个按钮）
 
+需要在关闭前做「未保存改动」之类的确认，用更底层的 `viewer.drawer({ preventClose, beforeClose })`，这层 layout 不再包装 cancel 拦截。
+
 #### DialogFormLayout
 
-弹窗形态的表单 layout，跟 `DrawerFormLayout` 是同源对偶。配合 `ctx.viewer.dialog({ closable: true, content })` 用。
+弹窗形态的表单 layout，跟 `DrawerFormLayout` 同形。配合 `ctx.viewer.dialog({ closable: true, content })` 用。
 
-跟 Drawer 版本的差异只有一点：title 是裸字符串（不带 close 图标），依赖 antd Modal 自带的右上角 X。注意 `viewer.dialog` 默认会禁用 antd 的原生 X——必须显式传 `closable: true` 才会出现。
+视觉上的差异只有关闭 X 的位置——Drawer 是 antd Drawer 自带的左上角 X，Dialog 是 antd Modal 自带的右上角 X。两边都依赖在 viewer 调用处显式传 `closable: true`，layout 自己都不渲染 close 图标。
 
 ```tsx
 import { DialogFormLayout } from '@nocobase/client-v2';
@@ -73,7 +76,7 @@ ctx.viewer.dialog({
 - **Drawer**：长表单、字段多、需要从一侧滑出占用整面（比如设置页的「添加 / 编辑」）
 - **Dialog**：短表单、需要快速确认（比如绑定、修改密码、二次验证）
 
-属性跟 `DrawerFormLayout` 完全一致，可以直接换。
+属性跟 `DrawerFormLayout` 基本一致，可以直接换。唯一区别：`DialogFormLayout` 多一个 `onCancel` 回调（Cancel 按钮和原生 X 都会触发），用于「丢弃改动」之类的确认。
 
 ### 表单字段
 
@@ -270,6 +273,48 @@ import { Table, DEFAULT_PAGE_SIZE } from '@nocobase/client-v2';
 - `PAGE_SIZE_OPTIONS`：建议的分页选项 `[5, 10, 20, 50, 100, 200]`
 - `SortHandle`：从 `@nocobase/client-v2` 导出的独立手柄组件，可以嵌进自定义列
 
+### 筛选
+
+#### CollectionFilter
+
+绑定 Collection 的筛选按钮。点击展开 Popover，里面是多条件筛选表单（字段选择器 + 操作符 + 取值控件）。Submit 收起 Popover 并通过 `onChange` 发出 NocoBase filter 参数；Reset 保持 Popover 打开并发出 `undefined`。
+
+```tsx
+import { CollectionFilter, ExtendCollectionsProvider } from '@nocobase/client-v2';
+import lockedUsersCollection from '../../collections/locked-users';
+
+function Page() {
+  const main = engine.context.dataSourceManager?.getDataSource?.('main');
+  const collection = main?.getCollection?.(lockedUsersCollection.name);
+
+  const listRequest = useRequest(
+    async (filter) => api.resource('lockedUsers').list({ ...(filter ? { filter } : {}) }),
+    { defaultParams: [undefined] },
+  );
+
+  return (
+    <ExtendCollectionsProvider collections={[lockedUsersCollection]}>
+      <CollectionFilter collection={collection} onChange={listRequest.run} t={t} />
+      {/* table … */}
+    </ExtendCollectionsProvider>
+  );
+}
+```
+
+主要属性：
+
+- `collection`：作为字段来源的 Collection。`undefined` 时按钮 disabled
+- `onChange: (filter) => void`：Submit 或 Reset 时触发，参数是编译好的 NocoBase filter（Reset 时为 `undefined`）。常见做法是直接转给 `listRequest.run`
+- `t`：翻译函数。建议传 `useT()`（来自插件 `locale.ts`），它会自动展开服务端返回的 `{{t("…")}}` 模板，否则字段标签、操作符标签可能显示成字面模板
+- `filterableFieldNames`：白名单，限制顶层可选字段
+- `noIgnore`：忽略白名单
+- `buttonText`：覆盖按钮文字，默认 `t('Filter')`
+- `showCount`：是否在按钮上显示当前条件数 `(N)`，默认 `true`
+- `popoverProps` / `buttonProps`：透传给 antd `Popover` / `Button`
+- `popoverMinWidth`：Popover 内容最小宽度，默认 `520`
+
+要筛选的 Collection 如果是 `schema-only`（服务端没自动发布到客户端 data source），用 `<ExtendCollectionsProvider>` 包一下当前页面，让 `CollectionFilter` 能解析到。
+
 ### 工具
 
 #### createFormRegistry
@@ -300,6 +345,43 @@ storageTypes.unregister('local');
 
 `name` 重复注册会用新条目覆盖旧的，同时打 `console.warn`——HMR 时不抛错，开发期能看到意外的重复。
 
+## data-source/
+
+跟数据源 / Collection 注册相关的组件。从 `@nocobase/client-v2` 顶层 export。
+
+### ExtendCollectionsProvider
+
+挂载期 Collection 注入器。在组件挂载时把传入的 collection 注册到目标 data source，卸载时移除；会监听 `dataSource:loaded` 自动重新注入，确保数据源 reload 时不会被清掉。
+
+```tsx
+import { ExtendCollectionsProvider } from '@nocobase/client-v2';
+import lockedUsersCollection from '../../collections/locked-users';
+
+// 模块级常量——保证引用稳定，避免 provider 每次父级重渲染都重跑 effect
+const collections = [lockedUsersCollection];
+
+export function LockedUsersPage() {
+  return (
+    <ExtendCollectionsProvider collections={collections}>
+      <LockedUsersPageInner />
+    </ExtendCollectionsProvider>
+  );
+}
+```
+
+主要属性：
+
+- `collections: CollectionOptions[]`：本次要注入的 Collection。Provider 只会注册当时不存在的那些，卸载时也只移除自己注册过的
+- `dataSource`：目标 data source key，默认 `'main'`
+- `children`：被注入 Collection 覆盖的子树
+
+什么时候用：
+
+- 服务端 collection 是 `schema-only`，不会自动发布到客户端 data source（比如 `lockedUsers`）
+- 需要一个纯客户端的 collection 镜像，只对当前页面有效，不污染全局
+
+常见搭配：跟 `<CollectionFilter>` 一起用——前者把 collection 挂上，后者读取并渲染筛选表单。
+
 ## 怎么决定加不加新组件
 
 - 出现两个及以上插件需要同一形态的字段或容器——抽到这里

package/src/components/form/DialogFormLayout.tsx

@@ -16,17 +16,9 @@ export interface DialogFormLayoutProps {
   title: React.ReactNode;
   /** Form body — typically a `<Form>` wrapping `<Form.Item>` fields. */
   children: React.ReactNode;
-  /**
-   * Called before the dialog is closed by the Cancel button or the
-   * top-right close (X) icon. Use for "discard changes" confirmations.
-   */
+  /** Called before the dialog is closed by the Cancel button or the top-right close (X) icon. Use for "discard changes" confirmations. */
   onCancel?: () => void | Promise<void>;
-  /**
-   * Called when the Submit button is clicked. Caller owns validation
-   * + the actual API call; the dialog is closed automatically when
-   * `onSubmit` resolves. Throw from `onSubmit` to keep the dialog open
-   * (e.g. on a validation error).
-   */
+  /** Called when the Submit button is clicked. Caller owns validation + the actual API call; the dialog is closed automatically when `onSubmit` resolves. Throw from `onSubmit` to keep the dialog open (e.g. on a validation error). */
   onSubmit?: () => void | Promise<void>;
   /** Drives the Submit button's loading state. */
   submitting?: boolean;
@@ -34,30 +26,14 @@ export interface DialogFormLayoutProps {
   submitText?: React.ReactNode;
   /** Override the Cancel button label. Defaults to "Cancel". */
   cancelText?: React.ReactNode;
-  /**
-   * Full override of the footer content. When provided, the default
-   * Cancel + Submit buttons are replaced. Useful for forms that need
-   * extra actions (e.g. Preview, Save draft).
-   */
+  /** Full override of the footer content. When provided, the default Cancel + Submit buttons are replaced. Useful for forms that need extra actions (e.g. Preview, Save draft). */
   footer?: React.ReactNode;
 }
 
 /**
- * Standard layout for dialog-hosted forms — the dialog counterpart of
- * `DrawerFormLayout`. Title sits left-aligned in the dialog's native
- * header (no inline close icon — the dialog provides its own X in the
- * top-right when opened with `viewer.dialog({ closable: true, ... })`),
- * the form body fills the middle, and a Cancel + Submit footer sits
- * at the bottom.
+ * Standard layout for dialog-hosted forms — the dialog counterpart of `DrawerFormLayout`. Title sits left-aligned in the dialog's native header, the form body fills the middle, and a Cancel + Submit footer sits at the bottom. Neither this layout nor `DrawerFormLayout` renders a close icon — both rely on the caller passing `closable: true` at the `viewer.dialog` / `viewer.drawer` call site to surface antd Modal's native top-right X (Dialog) or antd Drawer's native left-side X (Drawer).
  *
- * Why not just reuse `DrawerFormLayout`? `DrawerFormLayout` injects a
- * `<CloseOutlined>` button next to the title — that's the drawer
- * visual contract (close lives near the title in a side panel). In a
- * centered dialog the native top-right close button is the expected
- * affordance, so a separate layout keeps the visual contract clean.
- *
- * Callers own the `<Form>` instance, validation, and the actual API
- * call. This component only handles the chrome and close behaviour.
+ * Callers own the `<Form>` instance, validation, and the actual API call. This component only handles the chrome and close behaviour.
  *
  * Example:
  *

package/src/components/form/filter/CollectionFilter.tsx

@@ -0,0 +1,101 @@
+/**
+ * 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 { FilterOutlined } from '@ant-design/icons';
+import type { Collection } from '@nocobase/flow-engine';
+import { Button, type ButtonProps, Popover, type PopoverProps } from 'antd';
+import React, { FC, useState } from 'react';
+import { FilterContent } from '../../../flow/components/filter';
+import { CompiledFilter, FilterApplyAction, useFilterActionProps } from './useFilterActionProps';
+
+const identity = (s: string) => s;
+
+export interface CollectionFilterProps {
+  /** Collection whose fields drive the filter row's field picker. */
+  collection: Collection | undefined;
+  /** Called on Submit or Reset with the compiled NocoBase filter param (`undefined` when cleared). */
+  onChange: (filter: CompiledFilter) => void;
+  /** Translator. Defaults to identity. */
+  t?: (key: string, options?: Record<string, any>) => string;
+  /** Whitelist of root-level field names to expose. */
+  filterableFieldNames?: string[];
+  /** Bypass the `filterableFieldNames` whitelist. */
+  noIgnore?: boolean;
+  /** Override the trigger button's label. Defaults to `t('Filter')`, or the v1-style `t('{{count}} filter items', { count })` when conditions are present. */
+  buttonText?: React.ReactNode;
+  /** Swap the default `t('Filter')` label for v1's `t('{{count}} filter items', { count })` when conditions are present. Defaults to `true`. */
+  showCount?: boolean;
+  /** Pass-through props for the antd `<Popover>`. */
+  popoverProps?: Omit<PopoverProps, 'open' | 'onOpenChange' | 'content' | 'children'>;
+  /** Pass-through props for the trigger `<Button>`. */
+  buttonProps?: Omit<ButtonProps, 'icon' | 'type' | 'children' | 'onClick'>;
+  /** Min-width applied to the popover body. Defaults to `520`. */
+  popoverMinWidth?: number;
+}
+
+/**
+ * Filter button bound to a collection. Renders an antd `<Popover>` over a `<Button>`; the popover hosts a multi-condition filter form (field picker, operator, value). Submit dismisses the popover and emits the compiled filter via `onChange`; Reset keeps the popover open and emits `undefined`.
+ *
+ * Pair with `<ExtendCollectionsProvider>` when the target collection is client-only (e.g. a `schema-only` server collection that isn't auto-published to the v2 data source).
+ */
+export const CollectionFilter: FC<CollectionFilterProps> = (props) => {
+  const {
+    collection,
+    onChange,
+    t = identity,
+    filterableFieldNames,
+    noIgnore,
+    buttonText,
+    showCount = true,
+    popoverProps,
+    buttonProps,
+    popoverMinWidth = 520,
+  } = props;
+
+  const [open, setOpen] = useState(false);
+
+  const filterAction = useFilterActionProps({
+    collection,
+    filterableFieldNames,
+    noIgnore,
+    t,
+    onApply: (filter: CompiledFilter, action: FilterApplyAction) => {
+      onChange(filter);
+      if (action === 'submit') setOpen(false);
+    },
+  });
+
+  // Matches v1's `Filter.Action`: when at least one condition is set, the button label switches to the count-aware string (`"N 个筛选项"` in zh-CN). The button itself stays in the default (white) style — v1 never flipped it to `type='primary'`.
+  const label =
+    buttonText ??
+    (showCount && filterAction.conditionCount > 0
+      ? t('{{count}} filter items', { count: filterAction.conditionCount })
+      : t('Filter'));
+
+  return (
+    <Popover
+      trigger="click"
+      placement="bottomLeft"
+      {...popoverProps}
+      open={open}
+      onOpenChange={setOpen}
+      content={
+        <div style={{ minWidth: popoverMinWidth }}>
+          <FilterContent value={filterAction.value} ctx={filterAction.ctx} FilterItem={filterAction.FilterItem} />
+        </div>
+      }
+    >
+      <Button icon={<FilterOutlined />} disabled={!collection} {...buttonProps}>
+        {label}
+      </Button>
+    </Popover>
+  );
+};
+
+export default CollectionFilter;