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

package/src/components/README.md

@@ -0,0 +1,314 @@
+# client-v2 components
+
+This folder collects the React components that `@nocobase/client-v2` exposes to downstream plugins. Components are organized by directory — at the moment the main one is `form/`, which targets settings pages and form-shaped UIs.
+
+Skim this before writing a new plugin so you don't reinvent the wheel. Components are mostly orthogonal — import only what you need.
+
+## form/
+
+Components under `form/` cover the "settings page + form" shape. The typical recipe: open a form container with `ctx.viewer.drawer` / `ctx.viewer.dialog`, host an antd `Form` + `Form.Item` tree inside, and pick standard field controls from this folder.
+
+Grouped by purpose: form containers, form fields, data table, utilities.
+
+### Form containers
+
+#### DrawerFormLayout
+
+Drawer-style form layout. Pair with `ctx.viewer.drawer({ content })`.
+
+- Top: a close icon next to the title. Clicking close fires `onCancel` and dismisses the drawer
+- Bottom: default Cancel / Submit buttons; override the whole footer with `footer`
+- Middle: caller-supplied `<Form>` instance + fields
+
+```tsx
+import { DrawerFormLayout } from '@nocobase/client-v2';
+
+ctx.viewer.drawer({
+  width: '50%',
+  content: () => (
+    <DrawerFormLayout
+      title={t('Add authenticator')}
+      onSubmit={handleSubmit}
+      submitting={submitting}
+    >
+      <Form form={form} layout="vertical">
+        {/* fields */}
+      </Form>
+    </DrawerFormLayout>
+  ),
+});
+```
+
+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)
+- `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)
+
+#### 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.
+
+```tsx
+import { DialogFormLayout } from '@nocobase/client-v2';
+
+ctx.viewer.dialog({
+  closable: true,  // restore antd Modal's native top-right X
+  content: () => (
+    <DialogFormLayout title={t('Bind verifier')} onSubmit={handleSubmit}>
+      <Form form={form} layout="vertical">
+        {/* fields */}
+      </Form>
+    </DialogFormLayout>
+  ),
+});
+```
+
+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.
+
+### Form fields
+
+#### RemoteSelect
+
+A Select bound to an async option source. Framework-level — it knows nothing about NocoBase business resources; the caller passes a `request` function that fetches whatever it needs.
+
+```tsx
+import { RemoteSelect } from '@nocobase/client-v2';
+
+<Form.Item name="provider" label={t('Provider')}>
+  <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>
+```
+
+Key props:
+
+- `request: () => Promise`: fetch function, required. Returns either an array of items or an envelope object (combine with `selectItems` to pluck the array out)
+- `selectItems`: extractor that takes the `request` result and returns the option array. Use when the response is `{ items, meta }`-shaped
+- `fieldNames`: defaults to `{ label, value }` mapping; override with `mapOptions` when the raw item doesn't match
+- `mapOptions: (item, index) => ({ label, value })`: full override of option mapping
+- `cacheKey` / `refreshDeps` / `ready`: forwarded to ahooks `useRequest`; control caching and refresh timing
+- `onLoaded: (items, response) => void`: fires after data arrives; receives both the mapped item array and the raw response
+
+All other antd `Select` props (`mode` / `placeholder` / `disabled` / `value` / `onChange` / etc.) are passed through.
+
+`showSearch` + `allowClear` are on by default; search is local (filters by label). For server-side search, drive the search input through external state and pass it via `refreshDeps`, then read it inside `request`.
+
+#### EnvVariableInput
+
+A variable input restricted to the `$env` namespace. Designed for secret / credential fields — supports environment-variable references and adds password masking for plain literal values.
+
+```tsx
+import { EnvVariableInput } from '@nocobase/client-v2';
+
+<Form.Item name={['options', 'accessKeySecret']} label={t('Access Key Secret')}>
+  <EnvVariableInput password />
+</Form.Item>
+```
+
+Key props:
+
+- `password`: when enabled, non-variable literal values render through `Input.Password` so they're masked. Variable expressions like `{{ $env.X }}` stay visible and editable
+- `placeholder` / `disabled` / `value` / `onChange`: standard controlled-input props
+
+The persisted value is always a string: either a literal (`'literal'`) or a server-template reference (`'{{ $env.foo.bar }}'`). The server expands the reference at use time.
+
+#### VariableInput / VariableTextArea
+
+General-purpose variable inputs. Can reference any namespace registered on `flowEngine.context` — `$env`, `$user`, plus ad-hoc business namespaces like `$resetLink`.
+
+The two differ in shape:
+
+- `VariableInput`: single-line. Variables render as colored pills (compact "chips")
+- `VariableTextArea`: multi-line. Variables stay as raw `{{ ... }}` text — better for email templates and other long-form content where the literal `{{ ... }}` is the intended display (the server expands them at render time)
+
+```tsx
+import { VariableInput, VariableTextArea } from '@nocobase/client-v2';
+
+// Email subject — single line, pills
+<Form.Item name={['options', 'emailSubject']} label={t('Subject')}>
+  <VariableInput
+    namespaces={['$env']}
+    extraNodes={[
+      { name: '$resetLink', title: t('Reset password link'), type: 'string', paths: ['$resetLink'] },
+    ]}
+  />
+</Form.Item>
+
+// Email body — multi-line, literal
+<Form.Item name={['options', 'emailContentHTML']} label={t('Content')}>
+  <VariableTextArea namespaces={['$env']} rows={10} />
+</Form.Item>
+```
+
+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`
+- `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.
+
+#### 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.
+
+```tsx
+import { FileSizeInput } from '@nocobase/client-v2';
+
+<Form.Item name="maxFileSize" label={t('Max file size')}>
+  <FileSizeInput min={1} max={1024 * 1024 * 1024} defaultValue={20 * 1024 * 1024} />
+</Form.Item>
+```
+
+Key props:
+
+- `min` / `max`: allowed byte range; values out of range snap back on blur. Defaults: `min=1`, `max=Infinity`
+- `defaultValue`: drives the initial unit when the field is empty (e.g. 20 MB starts in the "MB" unit)
+- `value` / `onChange`: controlled-input contract; the value type is `number` (bytes)
+
+#### PasswordInput
+
+`antd Input.Password` plus an optional strength meter, ported from v1's
+`Password` component. Use for any "set / change password" form when you want
+to give the user the same visual signal they had in v1.
+
+```tsx
+import { PasswordInput } from '@nocobase/client-v2';
+
+<Form.Item name="newPassword" label={t('New password')} rules={[{ required: true }]}>
+  <PasswordInput autoComplete="new-password" checkStrength />
+</Form.Item>
+```
+
+Key props:
+
+- `checkStrength`: render a strength bar beneath the input. Defaults to `false`. The score is bucketed `[20, 40, 60, 80, 100]` and shown via a clipped gradient (orange) inside a grey track, matching v1
+- All other antd `Input.Password` props are passed through unchanged: `value` / `onChange` / `disabled` / `placeholder` / `autoComplete` / etc.
+
+The strength meter is purely a UX hint, NOT validation. Submitting a weak password is still allowed unless the server (or a separately installed password-policy plugin) rejects it. Wire up real password rules through `Form.Item.rules` or — when the open-source ↔ commercial extension point lands — the project's shared password-validator hook.
+
+#### JsonTextArea
+
+JSON input. The stored value is a JS object (not a string) — parsing happens live while typing and is finalized on blur.
+
+```tsx
+import { JsonTextArea } from '@nocobase/client-v2';
+
+<Form.Item name="customConfig" label={t('Custom config')}>
+  <JsonTextArea rows={6} json5 />
+</Form.Item>
+```
+
+Key props:
+
+- `space`: serialization indent. Defaults to `2`
+- `json5`: parse with JSON5 (tolerates trailing commas, comments, single quotes, etc.). Defaults to `false`
+- `showError`: render the parse error inline below the textarea. Defaults to `true`
+- All other antd `Input.TextArea` props are passed through
+
+`value` / `onChange` are typed as `unknown` because JSON values can be any shape. Tighten the contract with validators in `Form.Item.rules`.
+
+### Data table
+
+#### Table
+
+The standard settings-page table, built on antd `Table` with two additions:
+
+1. **Row index ↔ checkbox swap**: by default each row shows its ordinal ("1 / 2 / 3"); on hover or when selected the cell flips to a checkbox. The two elements are absolute-positioned in the same cell so neither steals layout space. Requires `rowSelection` to be present
+2. **Drag-and-drop reorder**: pass `isDraggable` to enable. Each row gets a drag handle on the left; `onSortEnd` fires when a row is dropped. The component does NOT mutate `dataSource` — the caller persists the move (`resource.move(...)`) and `refresh()`s
+
+```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) => { /* ... */ },
+  }}
+/>
+```
+
+Key props:
+
+- `rowKey`: required. Drag-sort and row-identity both depend on it
+- `showIndex`: defaults to `true`; disable to keep the cell at checkbox-only
+- `isDraggable`: drag-and-drop toggle. Defaults to `false` — when off the component is a thin antd `Table` superset
+- `onSortEnd: (from, to) => void | Promise`: fired when a row is dropped. Caller persists
+- `showSortHandle`: defaults to `true`; set false when you want the handle off (or embedded into a custom column via `<SortHandle />`)
+- All other antd `Table` props are passed through
+
+Companion exports:
+
+- `DEFAULT_PAGE_SIZE` (value `50`): suggested default page size
+- `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
+
+### Utilities
+
+#### createFormRegistry
+
+Factory for a namespaced "entry registry". Each call returns an independent registry instance backed by its own closure `Map`.
+
+```ts
+import { createFormRegistry, type FormRegistryEntry } from '@nocobase/client-v2';
+
+interface StorageType extends FormRegistryEntry {
+  // FormRegistryEntry requires at least `name: string`
+  title: string;
+  Component: React.ComponentType;
+}
+
+const storageTypes = createFormRegistry<StorageType>('file-manager/storage-types');
+
+storageTypes.register({ name: 'local', title: 'Local storage', Component: LocalStorageForm });
+storageTypes.register({ name: 's3', title: 'Amazon S3', Component: S3StorageForm });
+
+storageTypes.get('s3');
+storageTypes.list();
+storageTypes.has('local');
+storageTypes.unregister('local');
+```
+
+Use this when a plugin needs an extension point for "same name + same shape + different implementation" things (the file-manager's storage types, the verification plugin's OTP providers, etc.). It's a thin wrapper around `Map` that adds a namespace label and an HMR-friendly overwrite warning.
+
+Re-registering the same `name` overwrites the previous entry and emits a `console.warn` — HMR doesn't throw, and unintended duplicates surface in dev.
+
+## When to add a new component here
+
+- Two or more plugins need the same field or container shape — promote it to this folder
+- Cross-plugin reusable, but the abstraction couples to a specific business domain (e.g. "pick a verifier", "pick a data source") — keep it inside the producing plugin and export from that plugin's `client-v2/`
+- Before reaching for abstraction, check whether an existing component can be improved instead. `RemoteSelect.selectItems` is an example — it landed so envelope responses don't need their own component
+
+Two follow-ups after adding a new component:
+
+1. Add `export * from './XxxComponent'` to `form/index.tsx`
+2. Document it here so the next plugin migration finds it

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;