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

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

@@ -0,0 +1,312 @@
+# client-v2 components
+
+这里收纳 `@nocobase/client-v2` 暴露给业务插件复用的一组 React 组件。组件按目录组织——目前主要是 `form/`，给设置页和表单场景用。
+
+写新插件前先翻一遍这份说明，能省下不少重复造轮子的功夫。组件之间互相耦合很少，按需 import 就行。
+
+## form/
+
+`form/` 目录下的组件围绕「设置页 + 表单」这一类场景。常见用法是配合 `ctx.viewer.drawer` / `ctx.viewer.dialog` 打开一个表单容器，里面放 antd 的 `Form` + `Form.Item`，字段用这里提供的标准控件。
+
+下面按用途分四组：表单容器、表单字段、数据表、工具。
+
+### 表单容器
+
+#### DrawerFormLayout
+
+抽屉形态的表单 layout。配合 `ctx.viewer.drawer({ content })` 用。
+
+- 顶部 Header：左上角一个 close 图标 + 标题。点击 close 会触发 `onCancel` 然后关闭抽屉
+- 底部 Footer：默认 Cancel / Submit 两个按钮；可以用 `footer` 完全替换
+- 中间 children：调用方自己放 `<Form>` 实例 + 字段
+
+```tsx
+import { DrawerFormLayout } from '@nocobase/client-v2';
+
+ctx.viewer.drawer({
+  width: '50%',
+  content: () => (
+    <DrawerFormLayout
+      title={t('添加认证器')}
+      onSubmit={handleSubmit}
+      submitting={submitting}
+    >
+      <Form form={form} layout="vertical">
+        {/* 字段 */}
+      </Form>
+    </DrawerFormLayout>
+  ),
+});
+```
+
+主要属性：
+
+- `title`：标题节点（旁边带 close 图标）
+- `onCancel` / `onSubmit`：回调，resolve 后会自动关闭抽屉。Submit 里 throw 可以让抽屉保持打开（比如校验失败）
+- `submitting`：驱动 Submit 按钮的 loading
+- `submitText` / `cancelText`：按钮文字
+- `footer`：完全自定义 Footer 内容（覆盖默认两个按钮）
+
+#### DialogFormLayout
+
+弹窗形态的表单 layout，跟 `DrawerFormLayout` 是同源对偶。配合 `ctx.viewer.dialog({ closable: true, content })` 用。
+
+跟 Drawer 版本的差异只有一点：title 是裸字符串（不带 close 图标），依赖 antd Modal 自带的右上角 X。注意 `viewer.dialog` 默认会禁用 antd 的原生 X——必须显式传 `closable: true` 才会出现。
+
+```tsx
+import { DialogFormLayout } from '@nocobase/client-v2';
+
+ctx.viewer.dialog({
+  closable: true,  // 关键：开启 antd Modal 原生右上角 X
+  content: () => (
+    <DialogFormLayout title={t('绑定验证码')} onSubmit={handleSubmit}>
+      <Form form={form} layout="vertical">
+        {/* 字段 */}
+      </Form>
+    </DialogFormLayout>
+  ),
+});
+```
+
+什么时候选哪个？
+
+- **Drawer**：长表单、字段多、需要从一侧滑出占用整面（比如设置页的「添加 / 编辑」）
+- **Dialog**：短表单、需要快速确认（比如绑定、修改密码、二次验证）
+
+属性跟 `DrawerFormLayout` 完全一致，可以直接换。
+
+### 表单字段
+
+#### RemoteSelect
+
+异步拉数据的 Select。框架级组件——不感知 NocoBase 业务，调用方传一个 `request` 函数自己拉数据。
+
+```tsx
+import { RemoteSelect } from '@nocobase/client-v2';
+
+<Form.Item name="provider" label={t('服务商')}>
+  <RemoteSelect<{ name: string; title: string }>
+    request={async () => {
+      const response = await ctx.api.resource('smsOTPProviders').list();
+      return response?.data?.data || [];
+    }}
+    cacheKey="@nocobase/plugin-verification:smsOTPProviders:list"
+    mapOptions={(item) => ({ label: compileT(item.title), value: item.name })}
+  />
+</Form.Item>
+```
+
+主要属性：
+
+- `request: () => Promise`：拉数据，必填。可以返回数组，也可以返回带元数据的对象（搭配 `selectItems` 取出数组）
+- `selectItems`：从 `request` 返回值中抽出数组的函数。响应体是 `{ items, meta }` 形态时用
+- `fieldNames`：默认按 `{ label, value }` 字段映射；不匹配的时候用 `mapOptions` 完全自定义
+- `mapOptions: (item, index) => ({ label, value })`：完整覆盖映射逻辑
+- `cacheKey` / `refreshDeps` / `ready`：透传给 ahooks `useRequest`，控制缓存和 refresh 时机
+- `onLoaded: (items, response) => void`：拉到数据后的回调，能拿到原始响应
+
+剩下的 antd `Select` props（`mode` / `placeholder` / `disabled` / `value` / `onChange` 等）都原样透传。
+
+默认开启 `showSearch` + `allowClear`，搜索是本地模式（按 label 匹配）。要做服务端搜索，把搜索词放进 `refreshDeps`，在 `request` 里读出来发请求。
+
+#### EnvVariableInput
+
+`$env` 命名空间的变量输入器。专门给「密钥 / 凭证」这类字段用——支持环境变量引用，同时给纯字面值加 password mask。
+
+```tsx
+import { EnvVariableInput } from '@nocobase/client-v2';
+
+<Form.Item name={['options', 'accessKeySecret']} label={t('Access Key Secret')}>
+  <EnvVariableInput password />
+</Form.Item>
+```
+
+主要属性：
+
+- `password`：开启后，非变量的字面值会用 `Input.Password` 形态遮盖。变量表达式（比如 `{{ $env.X }}`）依然可见可编辑
+- `placeholder` / `disabled` / `value` / `onChange`：标准受控字段属性
+
+值的形态是字符串：`'literal'` 或 `'{{ $env.foo.bar }}'`。服务端在使用时再展开成实际值。
+
+#### VariableInput / VariableTextArea
+
+通用变量输入器。可以引用任意 `flowEngine.context` 注册的命名空间（`$env` / `$user` / 业务自定义的 `$resetLink` 等）。
+
+两者差异：
+
+- `VariableInput`：单行，变量渲染成彩色 pill（视觉上是「短标签」）
+- `VariableTextArea`：多行，变量保留 `{{ ... }}` 字面——适合邮件模板这种「字面 + 变量」混排的长文本
+
+```tsx
+import { VariableInput, VariableTextArea } from '@nocobase/client-v2';
+
+// 邮件主题：单行 pill 形态
+<Form.Item name={['options', 'emailSubject']} label={t('主题')}>
+  <VariableInput
+    namespaces={['$env']}
+    extraNodes={[
+      { name: '$resetLink', title: t('重置密码链接'), type: 'string', paths: ['$resetLink'] },
+    ]}
+  />
+</Form.Item>
+
+// 邮件正文：多行字面
+<Form.Item name={['options', 'emailContentHTML']} label={t('正文')}>
+  <VariableTextArea namespaces={['$env']} rows={10} />
+</Form.Item>
+```
+
+主要属性：
+
+- `namespaces`：限定可选的顶层命名空间。不传就用 `flowEngine.context` 里全部已注册的
+- `extraNodes`：在命名空间过滤后追加几条静态变量（用于 `$resetLink` 这类只在当前页面有意义的局部变量）
+- `converters`：覆盖默认的 path ↔ string 转换器。`EnvVariableInput` 就是用这个钩子把输出锁定到 `$env`
+- `value` / `onChange` / `placeholder` / `disabled`：标准受控字段属性
+
+底层共用 `VariableHybridInput`（`VariableInput`）和 `TextAreaWithContextSelector`（`VariableTextArea`），用同一套 MetaTree 数据。
+
+#### FileSizeInput
+
+文件大小输入器。值统一存字节数，UI 上配一个单位选择器（Byte / KB / MB / GB）。
+
+```tsx
+import { FileSizeInput } from '@nocobase/client-v2';
+
+<Form.Item name="maxFileSize" label={t('单文件大小上限')}>
+  <FileSizeInput min={1} max={1024 * 1024 * 1024} defaultValue={20 * 1024 * 1024} />
+</Form.Item>
+```
+
+主要属性：
+
+- `min` / `max`：允许的字节数区间，blur 时会自动 clamp 回界内。默认 `min=1`、`max=Infinity`
+- `defaultValue`：用来决定初次显示的单位（比如默认 20 MB 就会以 MB 单位起始）
+- `value` / `onChange`：受控字段，值类型是 `number`（字节）
+
+#### PasswordInput
+
+antd `Input.Password` 加一个可选的强度提示条，从 v1 的 `Password` 组件移植过来。用于「设置 / 修改密码」类表单——v1 → v2 迁移过来后视觉信号保持一致。
+
+```tsx
+import { PasswordInput } from '@nocobase/client-v2';
+
+<Form.Item name="newPassword" label={t('新密码')} rules={[{ required: true }]}>
+  <PasswordInput autoComplete="new-password" checkStrength />
+</Form.Item>
+```
+
+主要属性：
+
+- `checkStrength`：在输入框下方渲染一条强度提示。默认 `false`。强度评分按 `[20, 40, 60, 80, 100]` 分桶，用裁剪的橙色渐变填充在灰色底条上，配色跟 v1 保持一致
+- 其他 antd `Input.Password` 属性原样透传：`value` / `onChange` / `disabled` / `placeholder` / `autoComplete` 等
+
+强度条只是 UX 提示，**不是表单校验**。弱密码仍然能提交，除非 server（或单独安装的 password-policy 商业插件）拒绝。真正的密码规则通过 `Form.Item.rules` 或——等开源 ↔ 商业的 extension point 落地之后——项目共享的 password validator hook 接入。
+
+#### JsonTextArea
+
+JSON 输入器。存的值是 JS 对象（不是字符串），编辑时实时解析、blur 时校验。
+
+```tsx
+import { JsonTextArea } from '@nocobase/client-v2';
+
+<Form.Item name="customConfig" label={t('自定义配置')}>
+  <JsonTextArea rows={6} json5 />
+</Form.Item>
+```
+
+主要属性：
+
+- `space`：序列化缩进，默认 `2`
+- `json5`：开启后用 JSON5 解析（容忍尾逗号、注释、单引号等）。默认关
+- `showError`：解析失败时是否在下方显示错误消息。默认 `true`
+- 其他 antd `Input.TextArea` 的属性都透传
+
+`value` / `onChange` 的类型是 `unknown`——因为 JSON 可以是任意结构。调用方按业务约束在 `Form.Item.rules` 里加 validator 收紧类型。
+
+### 数据表
+
+#### Table
+
+设置页表格的标准组件，基于 antd `Table` 扩展了两点：
+
+1. **行索引和复选框切换**：默认状态显示「1 / 2 / 3」行号，悬停或选中时切换成 checkbox。两个元素绝对定位在同一格内，不会抢空间。需要 `rowSelection` 才生效
+2. **拖拽排序**：传 `isDraggable` 开启，每行左侧出现拖拽手柄；放下时触发 `onSortEnd`。组件不动 `dataSource`，由调用方在回调里跑 `resource.move(...)` 再 `refresh()`
+
+```tsx
+import { Table, DEFAULT_PAGE_SIZE } from '@nocobase/client-v2';
+
+<Table<AuthenticatorRecord>
+  rowKey="id"
+  loading={loading}
+  columns={columns}
+  dataSource={data?.records || []}
+  isDraggable
+  onSortEnd={async (from, to) => {
+    await resource.move({ sourceId: from.id, targetId: to.id });
+    refresh();
+  }}
+  rowSelection={{ selectedRowKeys, onChange: setSelectedRowKeys }}
+  pagination={{
+    current: page,
+    pageSize,
+    total: data?.total || 0,
+    onChange: (next, nextSize) => { /* ... */ },
+  }}
+/>
+```
+
+主要属性：
+
+- `rowKey`：必填。拖拽和行身份识别都依赖它
+- `showIndex`：默认 `true`，关掉就只显示 checkbox
+- `isDraggable`：开关拖拽。默认 `false`，关掉就是个加强版 antd Table
+- `onSortEnd: (from, to) => void | Promise`：拖拽放下时触发。调用方负责持久化
+- `showSortHandle`：默认 `true`，需要时可以隐藏手柄，自己在某列里嵌 `<SortHandle />`
+- 其他 antd `Table` props 全部透传
+
+附带导出：
+
+- `DEFAULT_PAGE_SIZE`（值 `50`）：建议的默认分页大小
+- `PAGE_SIZE_OPTIONS`：建议的分页选项 `[5, 10, 20, 50, 100, 200]`
+- `SortHandle`：从 `@nocobase/client-v2` 导出的独立手柄组件，可以嵌进自定义列
+
+### 工具
+
+#### createFormRegistry
+
+带命名空间的「条目注册表」工厂。每次调用返回一个独立的 registry 实例，闭包持有自己的 `Map`。
+
+```ts
+import { createFormRegistry, type FormRegistryEntry } from '@nocobase/client-v2';
+
+interface StorageType extends FormRegistryEntry {
+  // FormRegistryEntry 要求至少有 `name: string`
+  title: string;
+  Component: React.ComponentType;
+}
+
+const storageTypes = createFormRegistry<StorageType>('file-manager/storage-types');
+
+storageTypes.register({ name: 'local', title: '本地存储', Component: LocalStorageForm });
+storageTypes.register({ name: 's3', title: 'Amazon S3', Component: S3StorageForm });
+
+storageTypes.get('s3');
+storageTypes.list();
+storageTypes.has('local');
+storageTypes.unregister('local');
+```
+
+主要用在：插件需要给「同名 + 同形 + 不同实现」的东西做扩展点（比如 file-manager 的存储类型、verification 的 OTP provider）。比 `Map` 多了 namespace 标识和 HMR 友好的覆盖警告。
+
+`name` 重复注册会用新条目覆盖旧的，同时打 `console.warn`——HMR 时不抛错，开发期能看到意外的重复。
+
+## 怎么决定加不加新组件
+
+- 出现两个及以上插件需要同一形态的字段或容器——抽到这里
+- 跨插件复用、但耦合到具体业务领域（比如「选一个 verifier」「选一个数据源」）——留在业务插件里，从插件的 `client-v2/` 自己 export
+- 抽象前先看现有组件能不能改进：比如 `RemoteSelect` 的 `selectItems` 就是为了让带元数据的响应不需要再开新组件
+
+新增组件后别忘记两件事：
+
+1. 在 `form/index.tsx` 加一行 `export * from './XxxComponent'`
+2. 回来这份 README 补一节，方便后续插件迁移时找到

package/src/components/SwitchLanguage.tsx

@@ -0,0 +1,48 @@
+/**
+ * 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 { TranslationOutlined } from '@ant-design/icons';
+import { Dropdown, theme } from 'antd';
+import React from 'react';
+import { useApp } from '../hooks/useApp';
+import { useSystemSettings } from '../flow/system-settings';
+import languageCodes from '../locale/languageCodes';
+
+export function SwitchLanguage() {
+  const app = useApp();
+  const { token } = theme.useToken();
+  const { data } = useSystemSettings() || {};
+  const enabledLanguages: string[] = data?.data?.enabledLanguages || [];
+
+  if (enabledLanguages.length <= 1) {
+    return null;
+  }
+
+  const items = enabledLanguages
+    .filter((code) => languageCodes[code])
+    .map((code) => ({ key: code, label: languageCodes[code].label }));
+
+  return (
+    <Dropdown
+      menu={{
+        selectable: true,
+        defaultSelectedKeys: [app.apiClient.auth.locale],
+        items,
+        onClick: ({ key }) => {
+          app.apiClient.auth.setLocale(String(key));
+          window.location.reload();
+        },
+      }}
+    >
+      <TranslationOutlined style={{ fontSize: token.fontSizeXL, color: 'inherit' }} />
+    </Dropdown>
+  );
+}
+
+export default SwitchLanguage;

package/src/components/form/DialogFormLayout.tsx

@@ -0,0 +1,111 @@
+/**
+ * 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 { useFlowView } from '@nocobase/flow-engine';
+import { Button, Space } from 'antd';
+import React, { useCallback } from 'react';
+
+export interface DialogFormLayoutProps {
+  /** Header title rendered in the dialog's title slot. */
+  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.
+   */
+  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).
+   */
+  onSubmit?: () => void | Promise<void>;
+  /** Drives the Submit button's loading state. */
+  submitting?: boolean;
+  /** Override the Submit button label. Defaults to "Submit". */
+  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).
+   */
+  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.
+ *
+ * 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.
+ *
+ * Example:
+ *
+ * ```tsx
+ * ctx.viewer.dialog({
+ *   closable: true,                       // native top-right X
+ *   content: () => (
+ *     <DialogFormLayout
+ *       title={t('Bind verifier')}
+ *       onSubmit={handleSubmit}
+ *       submitting={submitting}
+ *       submitText={t('Bind')}
+ *     >
+ *       <Form form={form} layout="vertical">...</Form>
+ *     </DialogFormLayout>
+ *   ),
+ * });
+ * ```
+ */
+export function DialogFormLayout(props: DialogFormLayoutProps) {
+  const view = useFlowView();
+
+  const handleCancel = useCallback(async () => {
+    await props.onCancel?.();
+    await view.close();
+  }, [props, view]);
+
+  const handleSubmit = useCallback(async () => {
+    await props.onSubmit?.();
+    await view.close();
+  }, [props, view]);
+
+  return (
+    <div>
+      {view.Header ? <view.Header title={props.title} /> : null}
+      {props.children}
+      {view.Footer ? (
+        <view.Footer>
+          {props.footer ?? (
+            <Space>
+              <Button onClick={handleCancel}>{props.cancelText ?? 'Cancel'}</Button>
+              <Button type="primary" loading={props.submitting} onClick={handleSubmit}>
+                {props.submitText ?? 'Submit'}
+              </Button>
+            </Space>
+          )}
+        </view.Footer>
+      ) : null}
+    </div>
+  );
+}

package/src/components/form/DrawerFormLayout.tsx

@@ -7,22 +7,15 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { CloseOutlined } from '@ant-design/icons';
-import { css } from '@emotion/css';
 import { useFlowView } from '@nocobase/flow-engine';
 import { Button, Space } from 'antd';
 import React, { useCallback } from 'react';
 
 export interface DrawerFormLayoutProps {
-  /** Header title rendered next to the close (X) button. */
+  /** Header title rendered next to antd Drawer's native close (X) icon. */
   title: React.ReactNode;
   /** Form body — typically a `<Form>` wrapping `<Form.Item>` fields. */
   children: React.ReactNode;
-  /**
-   * Called before the drawer is closed by either the Cancel button or the
-   * header's 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 drawer is closed automatically when `onSubmit`
@@ -44,29 +37,26 @@ export interface DrawerFormLayoutProps {
   footer?: React.ReactNode;
 }
 
-const titleClassName = css`
-  display: inline-flex;
-  align-items: center;
-  gap: 8px;
-  margin-left: -8px;
-`;
-
 /**
- * Standard layout for drawer-hosted forms: a close-icon + title header on
- * top, the caller-provided form body in the middle, and a Cancel + Submit
- * footer at the bottom. Wraps `useFlowView()`'s `Header` / `Footer` slots
- * so the drawer chrome stays consistent across plugins.
+ * Standard layout for drawer-hosted forms: a title-only header on top
+ * (caller must open the drawer with `viewer.drawer({ closable: true })`
+ * so antd Drawer renders its native left-side X next to the title),
+ * the caller-provided form body in the middle, and a Cancel + Submit
+ * footer at the bottom. Wraps `useFlowView()`'s `Header` / `Footer`
+ * slots so the drawer chrome stays consistent across plugins.
+ *
+ * To intercept close (e.g. dirty-form confirmation), use the lower-level
+ * `viewer.drawer({ preventClose, beforeClose, ... })` hooks — this
+ * layout no longer wraps a custom close handler.
  *
  * Callers own the `<Form>` instance, validation, and the actual API call.
- * This component only handles the chrome and the close behaviour.
  */
 export function DrawerFormLayout(props: DrawerFormLayoutProps) {
   const view = useFlowView();
 
   const handleCancel = useCallback(async () => {
-    await props.onCancel?.();
     await view.close();
-  }, [props, view]);
+  }, [view]);
 
   const handleSubmit = useCallback(async () => {
     await props.onSubmit?.();
@@ -75,16 +65,7 @@ export function DrawerFormLayout(props: DrawerFormLayoutProps) {
 
   return (
     <div>
-      {view.Header ? (
-        <view.Header
-          title={
-            <span className={titleClassName}>
-              <Button type="text" size="small" icon={<CloseOutlined />} onClick={handleCancel} />
-              <span>{props.title}</span>
-            </span>
-          }
-        />
-      ) : null}
+      {view.Header ? <view.Header title={props.title} /> : null}
       {props.children}
       {view.Footer ? (
         <view.Footer>