@nocobase/client-v2 2.1.0-alpha.40 → 2.1.0-alpha.46

package/src/components/KeepAlive.tsx

@@ -0,0 +1,131 @@
+/**
+ * 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 { RouteContext } from '@ant-design/pro-layout';
+import _ from 'lodash';
+import React, { createContext, FC, memo, useContext, useRef } from 'react';
+import {
+  UNSAFE_DataRouterContext,
+  UNSAFE_DataRouterStateContext,
+  UNSAFE_LocationContext,
+  UNSAFE_RouteContext,
+} from 'react-router-dom';
+
+const KeepAliveContext = createContext(true);
+const hidden = { display: 'none' };
+
+export const KeepAliveProvider: FC<{ active: boolean; parentActive: boolean }> = memo(
+  ({ children, active, parentActive }) => {
+    const currentLocationContext = useContext(UNSAFE_LocationContext);
+    const currentRouteContext = useContext(UNSAFE_RouteContext);
+    const currentDataRouterContext = useContext(UNSAFE_DataRouterContext);
+    const currentDataRouterStateContext = useContext(UNSAFE_DataRouterStateContext);
+    const routeContextValue = useContext(RouteContext);
+
+    const prevLocationContextRef = useRef(currentLocationContext);
+    const prevRouteContextRef = useRef(currentRouteContext);
+    const prevDataRouterContextRef = useRef(currentDataRouterContext);
+    const prevDataRouterStateContextRef = useRef(currentDataRouterStateContext);
+    const prevRouteContextValueRef = useRef(routeContextValue);
+
+    if (active) {
+      prevDataRouterContextRef.current = currentDataRouterContext;
+      prevDataRouterStateContextRef.current = currentDataRouterStateContext;
+      prevRouteContextValueRef.current = routeContextValue;
+    }
+
+    if (
+      active &&
+      !_.isEqual(_.omit(prevLocationContextRef.current.location, 'key'), _.omit(currentLocationContext.location, 'key'))
+    ) {
+      prevLocationContextRef.current = currentLocationContext;
+    }
+
+    if (active && !_.isEqual(prevRouteContextRef.current, currentRouteContext)) {
+      prevRouteContextRef.current = currentRouteContext;
+    }
+
+    return (
+      <div style={active ? { height: '100%' } : hidden}>
+        <RouteContext.Provider value={prevRouteContextValueRef.current}>
+          <UNSAFE_DataRouterContext.Provider value={prevDataRouterContextRef.current}>
+            <UNSAFE_DataRouterStateContext.Provider value={prevDataRouterStateContextRef.current}>
+              <UNSAFE_LocationContext.Provider value={prevLocationContextRef.current}>
+                <UNSAFE_RouteContext.Provider value={prevRouteContextRef.current}>
+                  <KeepAliveContext.Provider value={parentActive === false ? false : active}>
+                    {children}
+                  </KeepAliveContext.Provider>
+                </UNSAFE_RouteContext.Provider>
+              </UNSAFE_LocationContext.Provider>
+            </UNSAFE_DataRouterStateContext.Provider>
+          </UNSAFE_DataRouterContext.Provider>
+        </RouteContext.Provider>
+      </div>
+    );
+  },
+);
+
+export const useKeepAlive = () => {
+  const active = useContext(KeepAliveContext);
+  return { active };
+};
+
+interface KeepAliveProps {
+  uid: string;
+  children: (uid: string) => React.ReactNode;
+}
+
+const MINIMUM_CACHED_PAGES = 5;
+const MAXIMUM_CACHED_PAGES = 15;
+
+const getMaxPageCount = () => {
+  const baseCount = MINIMUM_CACHED_PAGES;
+
+  try {
+    const memory = (navigator as any).deviceMemory;
+    if (memory) {
+      return Math.min(Math.max(baseCount, memory * 3), MAXIMUM_CACHED_PAGES);
+    }
+
+    const cores = navigator.hardwareConcurrency;
+    if (cores) {
+      return cores >= 8 ? MAXIMUM_CACHED_PAGES : cores >= 4 ? 7 : baseCount;
+    }
+
+    return baseCount;
+  } catch (e) {
+    return baseCount;
+  }
+};
+
+const MAX_RENDERED_PAGE_COUNT = getMaxPageCount();
+
+export const KeepAlive: FC<KeepAliveProps> = React.memo(({ children, uid }) => {
+  const { active } = useKeepAlive();
+  const renderedUidListRef = useRef<string[]>([]);
+
+  if (!renderedUidListRef.current.includes(uid)) {
+    renderedUidListRef.current.push(uid);
+    if (renderedUidListRef.current.length > MAX_RENDERED_PAGE_COUNT) {
+      renderedUidListRef.current = renderedUidListRef.current.slice(-MAX_RENDERED_PAGE_COUNT);
+    }
+  }
+
+  return (
+    <>
+      {renderedUidListRef.current.map((renderedUid) => (
+        <KeepAliveProvider active={renderedUid === uid} key={renderedUid} parentActive={active}>
+          {children(renderedUid)}
+        </KeepAliveProvider>
+      ))}
+    </>
+  );
+});
+
+KeepAlive.displayName = 'KeepAlive';

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
 
@@ -161,10 +164,59 @@ Key props:
 - `namespaces`: restrict the picker to specific top-level namespaces. Omit to expose every registered top-level property
 - `extraNodes`: static leaves appended after the namespace-filtered nodes. Use for variables that only make sense in the current page (e.g. `$resetLink`)
 - `converters`: override the default path ↔ string converters. `EnvVariableInput` uses this hook to lock its output to `$env`
+- `delimiters`: token pair wrapping the stored variable reference. Defaults to `['{{', '}}']` (Handlebars HTML-escaped). Pass `['{{{', '}}}']` for fields rendered as HTML where escaping would corrupt the variable value — e.g. the in-app message body
 - `value` / `onChange` / `placeholder` / `disabled`: standard controlled-input props
 
 Under the hood `VariableInput` wraps `VariableHybridInput` (inline pills), `VariableTextArea` wraps `TextAreaWithContextSelector` (textarea + variable button). Both share the same MetaTree.
 
+#### TypedVariableInput
+
+Typed-constant + variable hybrid input. Ported from v1 `Variable.Input`'s `useTypedConstant` pattern: an italic `x` button on the right triggers a Cascader switcher `[Null | Constant<types> | Variable<…namespaces>]`; the left side renders the matching editor (`Input` / `InputNumber` / `Select(True/False)` / `DatePicker`) or a pill carrying the variable path.
+
+Reach for this when a field **accepts both** a typed literal **and** a variable reference. The canonical example is `plugin-notification-email`'s SMTP `port` and `secure` fields: users can type a numeric port / boolean flag, or pass `{{ $env.SMTP_PORT }}` to read from environment variables.
+
+```tsx
+import { TypedVariableInput } from '@nocobase/client-v2';
+
+// Port — numeric constant + $env variable
+<Form.Item name={['options', 'port']} label={t('Port')} initialValue={465}>
+  <TypedVariableInput
+    types={[['number', { min: 1, max: 65535, step: 1 }]]}
+    namespaces={['$env']}
+  />
+</Form.Item>
+
+// Secure mode — boolean constant + $env variable
+<Form.Item name={['options', 'secure']} label={t('Secure')} initialValue={true}>
+  <TypedVariableInput types={['boolean']} namespaces={['$env']} />
+</Form.Item>
+```
+
+Key props:
+
+- `types`: allowed constant types. Shape mirrors v1 `useTypedConstant` — pass bare type names (`['number', 'boolean']`) or `[type, editorProps]` tuples (`[['number', { min, max, step }]]`) to forward props to the underlying antd editor. Defaults to `['string', 'number', 'boolean', 'date']`. **Even when only one type is allowed, the `Constant` entry still expands into a typed submenu** (Number / Boolean / Date / String) — matches v1 so users can see what type the constant is
+- `namespaces`: restrict the variable picker to specific top-level namespaces (e.g. `['$env']`). Omit to expose every namespace registered on `flowEngine.context`
+- `extraNodes`: static leaves appended after the namespace-filtered nodes
+- `nullable`: whether to expose the `Null` switcher entry. Default `true`. Combined with `Form.Item.rules={[{ required: true }]}`, the user can explicitly clear the field but submission is still blocked by validation — mirrors v1's "Null + required" pairing
+- `delimiters`: variable-token delimiters, default `['{{', '}}']` — same as `VariableInput`
+- `value` / `onChange` / `placeholder` / `disabled` / `style` / `className`: standard controlled-input props
+
+Value shape:
+
+- Constant: stored as the native type (`number` / `boolean` / `Date` / `string`)
+- Variable: a string like `'{{ $env.SMTP_PORT }}'`
+- Null: `null`
+
+When **not** to use it:
+
+- **Pure literal fields** (users will never pass a variable) → use the antd primitive directly (`InputNumber` / `Select` / `DatePicker` / `Input`) and skip the Cascader column overhead
+- **Pure variable fields** (users will never pass a literal) → use `EnvVariableInput` (`$env`-only, with optional password masking) or `VariableInput` (general-purpose)
+
+Capabilities skipped (present in v1, not yet ported to v2):
+
+- `object` constant type (JSON editor) — v2 has no inline "JSON editor + Cascader switcher" yet; add when there's a concrete caller
+- Async `loadChildren` cascading — most MetaTree namespaces are already eagerly resolved by `useFilteredMetaTree`, so this hasn't been needed
+
 #### FileSizeInput
 
 A byte-valued size input paired with a unit selector (Byte / KB / MB / GB). The persisted value is always in bytes; the displayed number is derived from the picked unit.
@@ -272,6 +324,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 +396,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 都会触发），用于「丢弃改动」之类的确认。
 
 ### 表单字段
 
@@ -161,10 +164,59 @@ import { VariableInput, VariableTextArea } from '@nocobase/client-v2';
 - `namespaces`：限定可选的顶层命名空间。不传就用 `flowEngine.context` 里全部已注册的
 - `extraNodes`：在命名空间过滤后追加几条静态变量（用于 `$resetLink` 这类只在当前页面有意义的局部变量）
 - `converters`：覆盖默认的 path ↔ string 转换器。`EnvVariableInput` 就是用这个钩子把输出锁定到 `$env`
+- `delimiters`：变量在存储字符串里使用的开闭分隔符，默认 `['{{', '}}']`（对应 Handlebars 的 HTML 转义形式）。若字段最终以 HTML 渲染、转义会破坏变量内容（如站内信正文），传 `['{{{', '}}}']` 走 Handlebars 的原样输出形式
 - `value` / `onChange` / `placeholder` / `disabled`：标准受控字段属性
 
 底层共用 `VariableHybridInput`（`VariableInput`）和 `TextAreaWithContextSelector`（`VariableTextArea`），用同一套 MetaTree 数据。
 
+#### TypedVariableInput
+
+类型化常量 + 变量混合输入器。移植 v1 `Variable.Input` 的 `useTypedConstant` 形态：右侧斜体 `x` 按钮触发 Cascader 切换 `[空值 | 常量<types> | 变量和密钥<…namespaces>]`，左侧根据当前模式渲染对应编辑器（`Input` / `InputNumber` / `Select(True/False)` / `DatePicker`）或一颗带变量路径的 pill。
+
+用于字段**同时接受**字面量**和**变量引用的场景。最典型的就是 `plugin-notification-email` 的 SMTP `port` 和 `secure`：可以填具体数字 / 布尔值，也可以填 `{{ $env.SMTP_PORT }}` 走环境变量。
+
+```tsx
+import { TypedVariableInput } from '@nocobase/client-v2';
+
+// 端口：数字常量 + $env 变量
+<Form.Item name={['options', 'port']} label={t('端口')} initialValue={465}>
+  <TypedVariableInput
+    types={[['number', { min: 1, max: 65535, step: 1 }]]}
+    namespaces={['$env']}
+  />
+</Form.Item>
+
+// 安全模式：布尔常量 + $env 变量
+<Form.Item name={['options', 'secure']} label={t('安全模式')} initialValue={true}>
+  <TypedVariableInput types={['boolean']} namespaces={['$env']} />
+</Form.Item>
+```
+
+主要属性：
+
+- `types`：允许的常量类型。形态对齐 v1 `useTypedConstant`，可以传裸类型名 `['number', 'boolean']`，也可以传 `[type, editorProps]` 元组 `[['number', { min, max, step }]]` 把 props 透传给底层 antd 编辑器。默认 `['string', 'number', 'boolean', 'date']`。**即使只允许一种类型，「常量」入口也会展开二级菜单**（数字 / 逻辑值 / 日期 / 字符串）——跟 v1 一致，让用户能直观看到当前常量是什么类型
+- `namespaces`：限定变量 picker 可选的顶层命名空间（如 `['$env']`）。不传就用 `flowEngine.context` 里所有已注册命名空间
+- `extraNodes`：在命名空间过滤后追加几条静态变量节点
+- `nullable`：是否暴露「空值」入口，默认 `true`。配合 `Form.Item.rules={[{ required: true }]}` 可以让用户能手动清空、但提交时会被校验拦截——跟 v1 的「空值 + required」组合一致
+- `delimiters`：变量 token 开闭分隔符，默认 `['{{', '}}']`，跟 `VariableInput` 一致
+- `value` / `onChange` / `placeholder` / `disabled` / `style` / `className`：标准受控字段属性
+
+值的形态：
+
+- 常量：原生类型直接存（`number` / `boolean` / `Date` / `string`）
+- 变量：字符串 `'{{ $env.SMTP_PORT }}'`
+- 空值：`null`
+
+什么时候**不该用**：
+
+- **纯字面量字段**（用户不会想填变量）→ 直接用 antd `InputNumber` / `Select` / `DatePicker` / `Input`，省掉 Cascader 那一格的视觉开销
+- **纯变量字段**（用户不会想填字面量）→ 用 `EnvVariableInput`（`$env` 专用，带 password mask）或 `VariableInput`（更通用）
+
+跳过的能力（v1 有但 v2 还没补）：
+
+- `object` 类型（JSON 编辑器）——v2 还没对应的「内联 JSON 编辑器 + Cascader 切换」组件，等真有需求再补
+- 异步 `loadChildren` 分支——大多数命名空间的 MetaTree 已经由 `useFilteredMetaTree` 提前展平，没遇到刚需
+
 #### FileSizeInput
 
 文件大小输入器。值统一存字节数，UI 上配一个单位选择器（Byte / KB / MB / GB）。
@@ -270,6 +322,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 +394,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/RouterBridge.tsx

@@ -7,11 +7,32 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { observable } from '@formily/reactive';
-import { useEffect, useMemo } from 'react';
-import { useLocation, useMatch, useMatches, useParams } from 'react-router-dom';
+import { useEffect } from 'react';
+import { useLocation, useMatches, useParams } from 'react-router-dom';
 import { Application } from '../Application';
 
+type LayoutMatchLike = {
+  id: string;
+  pathname: string;
+};
+
+type LayoutDefinitionLike = {
+  routeName: string;
+};
+
+export function findDeepestLayoutMatch(layouts: LayoutDefinitionLike[] = [], matches: LayoutMatchLike[] = []) {
+  const layoutRouteNames = new Set(layouts.map((layout) => layout.routeName));
+
+  for (let index = matches.length - 1; index >= 0; index -= 1) {
+    const match = matches[index];
+    if (layoutRouteNames.has(match.id)) {
+      return match;
+    }
+  }
+
+  return null;
+}
+
 export function useRouterSync(app: Application) {
   const params = useParams();
   const location = useLocation();
@@ -20,13 +41,16 @@ export function useRouterSync(app: Application) {
   useEffect(() => {
     const last = matches[matches.length - 1];
     if (!last) return;
+    const layoutMatch = findDeepestLayoutMatch(app.layoutManager?.listLayouts?.(), matches);
     engine.context['_observableCache']['route'] = {
       name: last.id,
       pathname: last.pathname,
       path: last.handle?.['path'] || null,
       params,
+      layoutRouteName: layoutMatch?.id,
+      layoutBasePathname: layoutMatch?.pathname,
     };
-  }, [engine.context, params, matches]);
+  }, [app, engine.context, params, matches]);
   useEffect(() => {
     engine.context['_observableCache']['location'] = location;
   }, [engine.context, location]);

package/src/components/__tests__/KeepAlive.test.tsx

@@ -0,0 +1,63 @@
+/**
+ * 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 { render, screen, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { createMemoryRouter, Outlet, RouterProvider, useParams } from 'react-router-dom';
+import { describe, expect, it } from 'vitest';
+import { KeepAlive } from '../KeepAlive';
+
+describe('KeepAlive', () => {
+  it('keeps inactive outlet pages mounted while switching route params', async () => {
+    const events: string[] = [];
+
+    const Page = () => {
+      const { name } = useParams();
+      useEffect(() => {
+        events.push(`mount:${name}`);
+        return () => {
+          events.push(`unmount:${name}`);
+        };
+      }, [name]);
+
+      return <div>page {name}</div>;
+    };
+
+    const Layout = () => {
+      const { name } = useParams();
+      return <KeepAlive uid={name || ''}>{() => <Outlet />}</KeepAlive>;
+    };
+
+    const router = createMemoryRouter(
+      [
+        {
+          path: '/:name',
+          element: <Layout />,
+          children: [{ index: true, element: <Page /> }],
+        },
+      ],
+      {
+        initialEntries: ['/page-a'],
+      },
+    );
+
+    render(<RouterProvider router={router} />);
+
+    expect(await screen.findByText('page page-a')).toBeInTheDocument();
+
+    await router.navigate('/page-b');
+
+    expect(await screen.findByText('page page-b')).toBeInTheDocument();
+    expect(screen.getByText('page page-a')).toBeInTheDocument();
+
+    await waitFor(() => {
+      expect(events).toEqual(['mount:page-a', 'mount:page-b']);
+    });
+  });
+});