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

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,6 +164,7 @@ 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.
@@ -272,6 +276,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 +348,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,6 +164,7 @@ 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 数据。
@@ -270,6 +274,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 +346,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']);
+    });
+  });
+});

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

@@ -0,0 +1,27 @@
+/**
+ * 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 { findDeepestLayoutMatch } from '../RouterBridge';
+
+describe('RouterBridge', () => {
+  it('uses the deepest matched layout route as layout base pathname', () => {
+    const match = findDeepestLayoutMatch(
+      [{ routeName: 'admin' }, { routeName: 'admin.settings.publicForms' }],
+      [
+        { id: 'admin', pathname: '/admin' },
+        { id: 'admin.settings', pathname: '/admin/settings' },
+        { id: 'admin.settings.publicForms', pathname: '/admin/settings/public-forms' },
+        { id: 'admin.settings.publicForms.page.view', pathname: '/admin/settings/public-forms/form-1/view/popup' },
+      ],
+    );
+
+    expect(match?.pathname).toBe('/admin/settings/public-forms');
+  });
+});

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:
  *