@zeroman.yang/react-auto-components 0.1.2 → 0.1.3

package/docs/i18n/zh-CN/README.md

@@ -12,10 +12,14 @@
 
 ## 项目状态
 
-当前版本为 0.1.2，API 仍可能发生变化。需要 React 19。该包提供 ESM 和 TypeScript 类型声明。内置界面文本默认为中文，可通过 AutoConfigProvider.config.t 进行翻译。
+当前版本为 0.1.3，API 仍可能发生变化。需要 React 19。该包提供 ESM 和 TypeScript 类型声明。内置界面文本默认为英文，可通过 AutoConfigProvider.config.t 进行翻译。
 
 使用 `pnpm add @zeroman.yang/react-auto-components` 安装（npm、yarn 同样可用）。peer dependency 为 React 19 与 react-dom 19。在入口引入一次样式：`import "@zeroman.yang/react-auto-components/style.css"`。
 
+在应用入口引入一次 `import "@zeroman.yang/react-auto-components/style.css"`。缺少样式时，开发模式警告 `RAC-CSS-MISSING`。
+
+XLSX 导出缺少 `exportXlsx` 适配器时为 `RAC-TABLE-XLSX`；无法加载可选依赖 `exceljs` 时为 `RAC-XLSX-DEP`。从 `@zeroman.yang/react-auto-components/xlsx` 导入并传入适配器，按需运行 `pnpm add exceljs`。CSV 和 JSON 不需要它。
+
 - [在线演示 (GitHub Pages)](https://zeroman.github.io/react-auto-components/)
 - [贡献指南](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/zh-CN/CONTRIBUTING.md)
 - [变更记录](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/zh-CN/CHANGELOG.md)
@@ -99,7 +103,7 @@ t 回调接收一个消息键和一个回退文本。在翻译内置消息时，
 | 组件 | 主要能力 |
 | --- | --- |
 | AutoForm | 多种原生字段、虚拟选项、级联、上传适配、自定义渲染、联动、动态显隐、异步规则、受控状态、失败保留输入 |
-| AutoSearchPanel | 基本/更多条件、手动/即时查询、重置、排序标签、统一查询 AST 与 RSQL 序列化 |
+| AutoSearch | 基本/更多条件、手动/即时查询、重置、排序标签、统一查询 AST 与 RSQL 序列化 |
 | AutoTable | 本地/远程数据、多列排序、列筛选、分页、稳定选择、虚拟化、树形/详情展开、汇总、合并单元格、CRUD、右键菜单、复制 |
 | AutoDialog | 声明式/命令式、隔离的 Provider、草稿、关闭拦截、焦点管理、拖动、全屏、异步提交 |
 | AutoTabs | 横向/纵向、嵌套、权限、禁用、保留面板状态、刷新 |
@@ -215,3 +219,5 @@ pnpm test:e2e
 AutoChat 提供轻量的对话布局，支持流式跟随、历史消息加载和消息输入框。传入 React 内容或 renderMessage 即可渲染消息，无需额外的运行时依赖。
 
 [AutoChat API](auto-chat.md)
+
+回调抛错之后组件会怎样，见行为契约：[AutoForm](auto-form.md)、[AutoSearch](auto-search.md)、[AutoTable](auto-table.md)、[AutoDialog](auto-dialog.md)、[AutoTabs](auto-tabs.md)、[AutoMenu](auto-menu.md)。开发者错误码：[errors.md](errors.md)。

package/docs/i18n/zh-CN/auto-dialog.md

@@ -0,0 +1,64 @@
+# AutoDialog
+
+[English](../../auto-dialog.md) | **简体中文** | [繁體中文](../zh-TW/auto-dialog.md) | [日本語](../ja/auto-dialog.md) | [한국어](../ko/auto-dialog.md) | [Español](../es/auto-dialog.md) | [Français](../fr/auto-dialog.md) | [Deutsch](../de/auto-dialog.md) | [Português (Brasil)](../pt-BR/auto-dialog.md) | [Русский](../ru/auto-dialog.md)
+
+模态弹窗。可以声明式（`<AutoDialog open>`），也可以命令式（`useAutoDialog().open()`）。传入 `fields` 会渲染 [AutoForm](auto-form.md)。不传字段时渲染 `content`。
+
+## 用法
+
+```tsx
+import {
+  AutoDialogProvider,
+  useAutoDialog,
+} from "@zeroman.yang/react-auto-components";
+import "@zeroman.yang/react-auto-components/style.css";
+
+function EditButton() {
+  const dialog = useAutoDialog();
+  return (
+    <button
+      onClick={() =>
+        dialog.open({
+          title: "编辑",
+          fields: [{ name: "name", label: "姓名", required: true }],
+          onSubmit: async (values) => save(values),
+        })
+      }
+    >
+      编辑
+    </button>
+  );
+}
+
+<AutoDialogProvider>
+  <EditButton />
+</AutoDialogProvider>
+```
+
+在 provider 外调用 `useAutoDialog()` 会抛 `RAC-DIALOG-PROVIDER`。声明式 `<AutoDialog open onOpenChange>` 不需要 provider。
+
+## 行为与属性
+
+| 属性 | 行为 |
+| --- | --- |
+| `open`、`onOpenChange` | 仅声明式。`onOpenChange(false)` 走关闭流程。 |
+| `fields` | 正文里的 schema 表单。校验规则与 AutoForm 相同。 |
+| `content` | 没有 `fields` 时使用。 |
+| `onSubmit(values)` | 校验通过后调用。**reject 或 throw：弹窗保持打开，显示 `error.message`，值保留。** resolve 后仍会走 `beforeClose`。 |
+| `beforeClose(reason)` | `reason` 为 `"submit"`、`"cancel"` 或 `"close"`。**返回 `false` 则保持打开。throw 也保持打开并显示消息。** |
+| `onClose(reason)` | 只有真正关掉之后才调用。 |
+| `draftKey` | 草稿存在 `${namespace}:draft:${draftKey}`，成功提交后删除。不传则不存储。 |
+| `showReset` | 显示表单重置。 |
+| `hideFooter` | 隐藏默认的确认/取消。用 `footer` 自己画。 |
+| `draggable` | 拖标题栏。全屏时忽略。 |
+| `width` | 像素。默认 `560`。 |
+| `fullscreen` | 初始全屏。标题栏按钮可切换。 |
+| `size` | 回落到 provider 的尺寸。默认 `"medium"`。 |
+
+`useAutoDialog().open()` 返回的 `close()` 在 `beforeClose` 拦住时 resolve `false`。
+
+命令式弹窗可以叠多层。每次 `open()` 返回 `{ id, close }`。`close(id)` 关掉对应的一层。
+
+## 前置条件
+
+入口引入一次 `style.css`。`AutoConfigProvider` 可选。它的 `namespace` 会进入 `draftKey` 的存储键，`t` 翻译内置按钮。它不能代替 `AutoDialogProvider`。

package/docs/i18n/zh-CN/auto-form.md

@@ -0,0 +1,62 @@
+# AutoForm
+
+[English](../../auto-form.md) | **简体中文** | [繁體中文](../zh-TW/auto-form.md) | [日本語](../ja/auto-form.md) | [한국어](../ko/auto-form.md) | [Español](../es/auto-form.md) | [Français](../fr/auto-form.md) | [Deutsch](../de/auto-form.md) | [Português (Brasil)](../pt-BR/auto-form.md) | [Русский](../ru/auto-form.md)
+
+按 schema 渲染的表单。控件、校验和提交都在这里。`AutoSearch` 和 `AutoDialog` 内部也渲染 `AutoForm`，所以下面的回调规则对它们同样有效。
+
+`Field<T>` 按 `type` 做判别联合。`select` 不给 `options`、`daterange` 配标量、标量字段上写 `match: "between"`，都是 TypeScript 错误。`AnyField` 和 `unsafeField()` 是逃生舱；开发模式仍会警告。错误码见 [errors.md](errors.md)。
+
+## 用法
+
+```tsx
+import { AutoForm, type Field } from "@zeroman.yang/react-auto-components";
+import "@zeroman.yang/react-auto-components/style.css";
+
+type Draft = { name: string; status: string };
+const fields: Field<Draft>[] = [
+  { name: "name", label: "姓名", required: true },
+  {
+    name: "status",
+    type: "select",
+    label: "状态",
+    options: [{ value: "open", label: "进行中" }],
+  },
+];
+
+<AutoForm<Draft> fields={fields} onSubmit={async (value) => save(value)} />
+```
+
+## 行为与属性
+
+| 属性 | 行为 |
+| --- | --- |
+| `fields` | `readonly Field<T>[]`。不写 `type` 就是文本框。`name` 重复会在挂载时抛 `RAC-FIELD-DUPLICATE`。 |
+| `value` | 受控值。与内部状态不同时，表单会抄过来并清空错误。父组件不理 `onChange`，输入会弹回。 |
+| `defaultValue` | 非受控初值，也是重置目标。字段自己的 `defaultValue` 补上没写的键。用 `structuredClone` 复制。 |
+| `onChange` | 每次接受的修改都会调用，包括字段 `onChange` 返回的补丁。 |
+| `onSubmit(value)` | 只在校验通过后调用。resolve 即结束。**reject 或 throw：值保留，操作区下方显示 `error.message`，不会重置。** |
+| `onReset` | 点重置或调用 `handle.reset()` 之后触发。 |
+| `disabled` | 禁止编辑和提交。默认 `false`。 |
+| `readOnly` | 只显示值，不渲染输入框。默认 `false`。 |
+| `columns` | 栅格列数。默认 `2`。`span` 不会超过它。`lineBreak` 独占一行。 |
+| `actions` | 内置提交和重置。默认 `true`。父组件自己画按钮时设为 `false`（搜索和弹窗就是这样）。 |
+| `submitLabel`、`resetLabel` | 替换内置文案。默认文案经 `config.t` 翻译。 |
+| 标签 | `labelPosition` 默认 `"top"`。`labelWidth` 默认 `"auto"`（测量后，最多占字段宽度的 45%）。`size` 和 `density` 回落到 `AutoConfigProvider`。 |
+
+## 回调抛错之后
+
+| 回调 | 结果 |
+| --- | --- |
+| `onSubmit` | 被捕获。草稿保留。显示消息。不重置。 |
+| 字段 `rules` | 按字段捕获。抛出的消息变成该字段的错误。后面的规则不再跑。 |
+| 字段 `onChange` | 不捕获。表单仍是上一次的值，这次按键不会写入。 |
+| `upload` | 拒绝后，错误显示在文件框下面，不写入值。`reset()` 会 abort `AbortSignal`，迟到的结果被丢掉。 |
+| 上传未完成就提交 | `validate()` 返回 `false`，并显示「请等待上传」的内置文案。不会调用 `onSubmit`。 |
+| `hidden`、`disabled` 或 `canAccess` 不通过 | 该字段不参与校验，即使 `required`。 |
+| `required` 为空 | `undefined`、`null`、`""` 或空数组会挡住提交。文案是 `"{label} is required"`，再走 `config.t`。 |
+
+`handle.validate()` resolve `true` 或 `false`，不抛错。`handle.reset()` 清错误和上传状态。
+
+## 前置条件
+
+入口引入一次 `style.css`。开发模式读不到 `--auto-text` 时警告 `RAC-CSS-MISSING`。`AutoConfigProvider` 可选，用来提供标签布局、尺寸、密度、`t`、`canAccess` 和存储。它不提供弹窗。

package/docs/i18n/zh-CN/auto-menu.md

@@ -0,0 +1,47 @@
+# AutoMenu
+
+[English](../../auto-menu.md) | **简体中文** | [繁體中文](../zh-TW/auto-menu.md) | [日本語](../ja/auto-menu.md) | [한국어](../ko/auto-menu.md) | [Español](../es/auto-menu.md) | [Français](../fr/auto-menu.md) | [Deutsch](../de/auto-menu.md) | [Português (Brasil)](../pt-BR/auto-menu.md) | [Русский](../ru/auto-menu.md)
+
+侧栏。条目可以嵌套、收成图标轨，并带图标、说明和徽章。它是导航，不是标签面板。面板用 [AutoTabs](auto-tabs.md)。
+
+## 用法
+
+```tsx
+import { AutoMenu } from "@zeroman.yang/react-auto-components";
+import "@zeroman.yang/react-auto-components/style.css";
+
+<AutoMenu
+  label="主导航"
+  items={[
+    { id: "inbox", label: "收件箱" },
+    {
+      id: "settings",
+      label: "设置",
+      children: [{ id: "profile", label: "资料" }],
+    },
+  ]}
+  onChange={(id) => navigate(id)}
+/>
+```
+
+## 行为与属性
+
+| 属性 | 行为 |
+| --- | --- |
+| `items` | `id` 在整棵树里唯一。`hidden` 和 `canAccess` 不通过的条目会被丢掉。`children` 如果指回祖先，整支会被丢掉，避免坏 schema 无限递归。 |
+| `value` | 受控的选中叶子 id。省略则选择留在组件内部。 |
+| `defaultValue` | 非受控的初始叶子。对不上叶子时，选中第一个可用叶子。 |
+| `onChange(id, item, path)` | **不捕获。** `path` 是从根到叶子的 id 链。有 `children` 的父项只切换展开，不选中。 |
+| `collapsible` | 默认 `false`。为 `true` 时，按钮可以收成图标轨。 |
+| `collapsed` | 受控的图标轨。省略则用 `defaultCollapsed`（默认 `false`）。 |
+| `onCollapsedChange` | **不捕获。** 参数是下一个布尔值。如果 `collapsed` 受控，你不更新它，图标轨就不会动。 |
+| `disabled` | 禁用该项及其子孙。选择时会跳过禁用项。 |
+| `label` | 分组标题，也是导航的无障碍名称。 |
+| `header`、`footer` | 列表上下的插槽。 |
+| `size`、`density` | 覆盖 provider。菜单先读 `config.menu`，再读全局尺寸和密度。 |
+
+键盘移动留在菜单内。选中叶子本身不会跳转；只有 `onChange` 是信号。
+
+## 前置条件
+
+入口引入一次 `style.css`（开发模式 `RAC-CSS-MISSING`）。`AutoConfigProvider` 可选。权限走 `config.canAccess`。

package/docs/i18n/zh-CN/auto-search.md

@@ -0,0 +1,55 @@
+# AutoSearch
+
+[English](../../auto-search.md) | **简体中文** | [繁體中文](../zh-TW/auto-search.md) | [日本語](../ja/auto-search.md) | [한국어](../ko/auto-search.md) | [Español](../es/auto-search.md) | [Français](../fr/auto-search.md) | [Deutsch](../de/auto-search.md) | [Português (Brasil)](../pt-BR/auto-search.md) | [Русский](../ru/auto-search.md)
+
+搜索表单。内部渲染 `AutoForm`，同时给出 `QueryNode` 和原始值。字段规则，包括抛错后的行为，与 [AutoForm](auto-form.md) 相同。
+
+`AutoSearchPanel` 和 `AutoSearchPanelProps` 是 `AutoSearch` 与 `AutoSearchProps` 的已弃用别名。
+
+## 用法
+
+```tsx
+import { AutoSearch } from "@zeroman.yang/react-auto-components";
+import "@zeroman.yang/react-auto-components/style.css";
+
+<AutoSearch
+  fields={[
+    { name: "name", label: "名称", match: "contains" },
+    { name: "period", type: "daterange", label: "周期", match: "between" },
+  ]}
+  onSearch={(query, values) => load(query, values)}
+/>
+```
+
+`type` 为 `daterange` 或 `match` 为 `"between"` 时，模型字段必须是两项元组。
+
+## 行为与属性
+
+| 属性 | 行为 |
+| --- | --- |
+| `fields` | 与 AutoForm 相同的 `Field<T>`。`more: true` 的字段在展开「更多」之前隐藏。隐藏字段不进入查询。 |
+| `onSearch(query, values)` | 必填。**throw 或 reject：内部表单捕获它，值保留，显示 `error.message`。不会因此重置。** |
+| `onChange` | 编辑和重置都会触发。即时搜索时，它发生在 `onSearch` 之前。 |
+| `mode` | 默认 `"manual"`：点搜索才查。`"instant"` 每次修改也查。 |
+| `value`、`defaultValue` | 受控和重置规则与 AutoForm 相同。 |
+| `columns` | 默认 `3`。 |
+| `sortTags` | 你自己的按钮。`onRemove` 不捕获。 |
+| 标签属性 | 与 AutoForm 相同。传入的布局优先于 provider。 |
+
+## 查询值
+
+| `match` | 值 |
+| --- | --- |
+| 省略 | `"eq"`；值是数组时为 `"in"`。 |
+| `"contains"` | 子串。`ignoreCase: true` 忽略大小写。 |
+| `"between"` | `[from, to]`。标量会警告 `RAC-FIELD-BETWEEN`，并且匹配不到行。 |
+| `"isNull"` | 匹配 null 或 undefined。输入的值被忽略。 |
+| 空值 | `undefined`、`null`、`""` 和空数组会被省略，`"isNull"` 除外。 |
+
+`includeNull: true` 会再 OR 一个 `isNull`。`searchFields` 把同一次比较 OR 到这些行字段上，而不是只用 `name`。
+
+重置会恢复 `defaultValue`，然后立刻搜索。字段名不符合 `/^[\w.]+$/` 时，`serializeRsql` 抛 `RAC-QUERY-FIELD`。
+
+## 前置条件
+
+入口引入一次 `style.css`（开发模式 `RAC-CSS-MISSING`）。`AutoConfigProvider` 可选，只提供布局、翻译和权限。

package/docs/i18n/zh-CN/auto-table.md

@@ -0,0 +1,62 @@
+# AutoTable
+
+[English](../../auto-table.md) | **简体中文** | [繁體中文](../zh-TW/auto-table.md) | [日本語](../ja/auto-table.md) | [한국어](../ko/auto-table.md) | [Español](../es/auto-table.md) | [Français](../fr/auto-table.md) | [Deutsch](../de/auto-table.md) | [Português (Brasil)](../pt-BR/auto-table.md) | [Русский](../ru/auto-table.md)
+
+本地或远程数据的表格，带排序、筛选、选择、可选虚拟滚动，以及增删改弹窗。搜索字段遵循 [AutoSearch](auto-search.md)。新增和编辑弹窗遵循 [AutoDialog](auto-dialog.md) 与 [AutoForm](auto-form.md)。
+
+`data`、`dataSource`、`source` 只能提供一个；同时传递是类型错误。
+
+## 用法
+
+```tsx
+import { AutoTable } from "@zeroman.yang/react-auto-components";
+import { exportXlsx } from "@zeroman.yang/react-auto-components/xlsx";
+import "@zeroman.yang/react-auto-components/style.css";
+
+<AutoTable
+  id="orders"
+  rowKey="id"
+  data={rows}
+  columns={[{ key: "id", label: "编号" }]}
+  exportXlsx={exportXlsx}
+/>
+```
+
+`exportXlsx` 来自 `@zeroman.yang/react-auto-components/xlsx`，不是主入口。`exceljs` 是可选依赖，缺失时为 `RAC-XLSX-DEP`。
+
+## 行为与属性
+
+| 属性 | 行为 |
+| --- | --- |
+| `id` | 必填。设置键是 `${namespace}:table:${id}`。空 id 警告 `RAC-TABLE-ID`。 |
+| `rowKey` | 字段名或 `(row) => string`。已加载的行里必须唯一。缺失或重复警告 `RAC-TABLE-ROWID`。选择、展开和 `scrollToRow` 都用它。 |
+| `data` | 本地行。筛选和分页在浏览器里完成。 |
+| `dataSource(query, { signal })` | 远程分页。**reject：显示消息和重试按钮。abort 被忽略。** 返回 `{ rows, total }`，`total` 是筛选后的总条数，不是本页长度。 |
+| `columns` | 省略时用第一行的键，跳过 `_auto_*`。列的 `type` 只影响格式化，不是表单控件。 |
+| `pageSize` | 默认 `10`。`pagination` 默认 `true`。 |
+| `height` | 默认 `440` 像素。`"auto"` 填满已经有高度的父元素。 |
+| `virtual` | 可选。用 TanStack Virtual 测量行高。 |
+| `query`、`onQueryChange` | 受控查询。省略则页码、排序和筛选留在表格内（排序和筛选也跟随已保存的方案）。 |
+| `searchFields` | 渲染 `AutoSearch`。它的 `onSearch` 更新表格筛选。 |
+| `formFields` | 新增/编辑弹窗的 schema。省略时，列会变成文本或整数控件。 |
+| `onAdd`、`onEdit`、`onDelete` | 校验通过后由弹窗调用。**reject 或 throw：弹窗保持打开并显示 `error.message`。除非你的处理函数已经改了数据，否则行不会变。** |
+| `rowActions` | `onClick` 拒绝会被捕获，并在状态行显示约 2.5 秒；行不会被移除。 行菜单动作缺少 `onClick`，且 `action` 不是已注册的 `config.rowActions` 键时，选择该动作会在状态行显示 `RAC-ROW-ACTION`。提供 `onClick` 或注册对应的 `action`；两者都有时 `onClick` 优先。 |
+| `component` | 列的 `component` 未在 `AutoConfigProvider` 的 `config.columns` 中注册时，开发模式警告 `RAC-COLUMN-COMPONENT`，单元格使用默认格式。注册该键，或在列上提供 `render`、`format`、`sort`；列上的函数优先。 |
+| `source` | `source` 是 `AutoConfigProvider` 的 `config.sources` 中的数据源键。未知键会显示 `RAC-TABLE-SOURCE` 和重试按钮。注册该键，或改用 `data` / `dataSource`；三者只能提供一个。 |
+| `exportXlsx` | 只有 xlsx 需要。缺少适配器抛 `RAC-TABLE-XLSX`，状态行显示翻译后的适配器文案。CSV 和 JSON 是内置的。 |
+| `versions` | 提高 layout、sort、filter 或 export 的版本号，丢掉对应的已存方案。 |
+| `summaryValues` | 筛选结果的服务端合计，按列键索引。 |
+
+## 导出与设置
+
+`handle.export(format, scope)` 即使状态行显示错误也会 resolve，错误不会再抛出。远程表的 `scope: "filtered"` 会逐页拉取。最后一页之前出现空页会抛 `RAC-TABLE-EXPORT-PAGE`，不会下载半份文件。
+
+布局、排序、筛选和导出默认进 `config.storage`（即 `localStorage`），也可再走 `config.settings`。`settings.save` / `load` 失败会显示 "Could not save settings" 和重试按钮。内存中的表格继续可用。
+
+设置里的筛选 JSON 不合法时，显示翻译后的 "Invalid filter"，警告 `RAC-TABLE-FILTER`，并保留上一次筛选。`between` 必须是两项数组。`in` 必须是数组。
+
+`handle.reset()` 清排序、筛选、选择，并把布局收回列的默认值。`handle.refresh()` 重新请求 `dataSource`。`handle.scrollToRow(id)` 在该 id 未加载时什么也不做。
+
+## 前置条件
+
+入口引入一次 `style.css`。同一个源上有多个应用要持久化表格时，设置 `AutoConfigProvider` 的 `namespace`；默认是 `"auto"`。内置的新增/编辑弹窗用的是声明式对话框，不需要 `AutoDialogProvider`。只有 `useAutoDialog()` 需要它。

package/docs/i18n/zh-CN/auto-tabs.md

@@ -0,0 +1,99 @@
+# AutoTabs
+
+[English](../../auto-tabs.md) | **简体中文** | [繁體中文](../zh-TW/auto-tabs.md) | [日本語](../ja/auto-tabs.md) | [한국어](../ko/auto-tabs.md) | [Español](../es/auto-tabs.md) | [Français](../fr/auto-tabs.md) | [Deutsch](../de/auto-tabs.md) | [Português (Brasil)](../pt-BR/auto-tabs.md) | [Русский](../ru/auto-tabs.md)
+
+标签页。嵌套标签是另一组由 `children` 喂给的 `AutoTabs`，不是菜单。侧栏用 [AutoMenu](auto-menu.md)。
+
+## 用法
+
+```tsx
+import { AutoTabs } from "@zeroman.yang/react-auto-components";
+import "@zeroman.yang/react-auto-components/style.css";
+
+<AutoTabs
+  items={[
+    { id: "one", label: "其一", content: <p>第一页</p> },
+    { id: "two", label: "其二", content: <p>第二页</p>, disabled: true },
+  ]}
+/>
+```
+
+## 行为与属性
+
+| 属性 | 行为 |
+| --- | --- |
+| `items` | 每个标签要有稳定的 `id`。`hidden`（布尔或函数）以及 `canAccess` 不通过的标签会被去掉。 |
+| `value` | 受控路径，从根开始的 id 列表。嵌套选择是 `["parent", "child"]`。 |
+| `defaultValue` | 非受控的初始路径。 |
+| `onChange(path, item)` | **不捕获。** 抛错时由 React 报告。受控模式下，你还没提交的路径保持上次的值。 |
+| `mode` | 默认 `"horizontal"`。`"vertical"` 把标签竖排。 |
+| `keepMounted` | 默认 `true`：未选中的面板仍挂载，局部状态还在。`false` 会卸载它们。 |
+| `onRefresh` | 设置后，该标签显示刷新按钮。**不捕获。** |
+| `loading` | 在标签文字后加省略号。不阻止选择。 |
+| `size`、`density` | 覆盖 provider。标签先读 `config.tabs`，再读全局的 size 和 density。 |
+| `disabled` | 标签仍可见，但不能选。默认选中会跳过禁用标签。 |
+| `closable` | 分组提供了 `onClose` 时显示关闭按钮。焦点在该标签上时，Delete 也会请求关闭。 |
+| `onClose(path, item)` | 请调用方移除这个标签。**不捕获。** 嵌套组上报完整路径。调用方自己更新 `items`。 |
+| `lazy` | 默认 `false`。`true` 在第一次打开时才挂载面板。 |
+
+某一项如果有 `children`，就用嵌套标签代替 `content`。`defaultActive` 是嵌套层的非受控 id。
+
+## 动态标签
+
+`useAutoTabsWorkspace` 在没有路由器的情况下维护一组页面。把 `tabsProps` 传给 `AutoTabs`。`open` 会新增页面；如果这个 id 已经打开，就切过去并保留草稿。
+
+```tsx
+import {
+  AutoTabs,
+  useAutoTabsWorkspace,
+} from "@zeroman.yang/react-auto-components";
+
+const pages = {
+  home: { title: "工作台", render: () => <p>固定标签</p> },
+  order: {
+    title: "订单",
+    render: ({ tab, setState }) => (
+      <input
+        aria-label="草稿"
+        value={typeof tab.state === "string" ? tab.state : ""}
+        onChange={(event) => setState(event.target.value)}
+      />
+    ),
+  },
+};
+
+export function Orders() {
+  const workspace = useAutoTabsWorkspace({
+    workspaceId: "orders",
+    pages,
+    defaultTabs: [{ id: "home", page: "home", pinned: true }],
+  });
+  return (
+    <>
+      <button
+        type="button"
+        disabled={!workspace.ready}
+        onClick={() =>
+          workspace.open({
+            id: "order:1",
+            page: "order",
+            title: "订单 1",
+            params: { orderId: "1" },
+          })
+        }
+      >
+        打开订单
+      </button>
+      {workspace.ready && <AutoTabs {...workspace.tabsProps} />}
+    </>
+  );
+}
+```
+
+固定标签没有关闭按钮。关掉当前标签时，会选中下一个可用的邻居。`beforeClose` 返回 `false` 或抛错都会取消关闭。关闭按钮上的抛错会通过 `config.notify` 显示。标签、选中项、`params` 和 `state` 在挂载后从 `sessionStorage` 恢复。等到 `ready` 再调用 `open`。`storage: false` 只放在内存里。`"local"` 或存储适配器可以选择别的存储。键是 `${namespace}:tabs:${workspaceId}`。
+
+`tabsProps` 会打开 `lazy` 和 `keepMounted`：面板第一次访问时挂载，之后保持挂载。组件不会自己删标签。`onClose` 请工作区移除它。
+
+## 前置条件
+
+入口引入一次 `style.css`（开发模式 `RAC-CSS-MISSING`）。`AutoConfigProvider` 可选。

package/docs/i18n/zh-CN/errors.md

@@ -0,0 +1,112 @@
+# 错误码
+
+[English](../../errors.md) | **简体中文** | [繁體中文](../zh-TW/errors.md) | [日本語](../ja/errors.md) | [한국어](../ko/errors.md) | [Español](../es/errors.md) | [Français](../fr/errors.md) | [Deutsch](../de/errors.md) | [Português (Brasil)](../pt-BR/errors.md) | [Русский](../ru/errors.md)
+
+开发者错误抛出 `RacError`，或在开发模式 `console.warn`。正文始终是英文：
+
+```text
+[Component] 哪里错了。
+Fix: 怎么改。
+Code: RAC-…
+Docs: https://github.com/Zeroman/react-auto-components/blob/main/docs/errors.md#rac-…
+```
+
+界面文案仍走 `config.t`。`RacError.userKey` 是英文源句，宿主照旧翻译。控制台和异常本身保持英文，方便模型按报错修改。
+
+## RAC-FIELD-OPTIONS
+
+`type` 为 `select`、`select-v2`、`radio`、`checkbox` 或 `cascader`，但没有 `options`，或 `options` 是空数组。
+
+修复：传入 `options` 数组，或 `(values) => Option[]`。`autocomplete` 可以不传，它是带可选建议的文本框。
+
+## RAC-FIELD-RANGE
+
+`type` 为 `daterange` 或 `datetimerange`，但模型字段或当前值不是两项数组。
+
+修复：把字段类型写成 `[start, end]`。`dateValue` 默认 `"string"`（`YYYY-MM-DD`）。`"timestamp"` 存本地时区的毫秒时间戳。`null` 表示该端不限制。
+
+标量字符串或数字在 TypeScript 里直接报错，错误文本含 `RAC-FIELD-RANGE`。模型若是数组类型则能通过编译；运行值长度不是 2 时，开发模式会警告。
+
+## RAC-FIELD-BETWEEN
+
+`match: "between"` 的模型字段或当前值不是 `[from, to]`。
+
+修复：存成两项元组。标量不会命中任何行。`Field<T>` 上这同样是类型错误。
+
+## RAC-FIELD-CUSTOM
+
+`type: "custom"` 既没有 `render` 也没有 `component`。
+
+修复：传入 `render(context)`，或把 `component` 设为 `AutoConfigProvider` 的 `config.fields` 里的键。
+
+## RAC-FIELD-DUPLICATE
+
+两个字段 `name` 相同。表单挂载时 `defaults` 抛出。
+
+修复：名字唯一。`title`、`tip`、`append`、`button` 没有名字，不参与检查。
+
+## RAC-CSS-MISSING
+
+开发模式在 `:root` 上读不到 `--auto-text`。样式表会设置这个变量。没引入样式时页面是乱的，DOM 里看不出原因。
+
+修复：在应用入口写一次 `import "@zeroman.yang/react-auto-components/style.css"`。
+
+## RAC-TABLE-XLSX
+
+调用了 `export("xlsx")`，但没有传 `exportXlsx`。
+
+修复：`import { exportXlsx } from "@zeroman.yang/react-auto-components/xlsx"`，并传入 `exportXlsx={exportXlsx}`。界面仍显示翻译后的 "Configure the XLSX export adapter"。
+
+## RAC-XLSX-DEP
+
+xlsx 适配器加载不到 `exceljs`。它是 `optionalDependency`，普通安装可能把它跳过。
+
+修复：`pnpm add exceljs`。CSV 和 JSON 不需要它。
+
+## RAC-TABLE-EXPORT-PAGE
+
+远程导出时，最后一页之前出现了空页，因此没有保存文件。
+
+修复：`total` 要稳定，并且每一页都返回该 `pageIndex` 的行。界面显示翻译后的 "Export data is incomplete. Try again."。
+
+## RAC-TABLE-ROWID
+
+已加载的行里 `rowKey` 缺失或重复。仅开发警告。
+
+修复：每行要有稳定且唯一的字符串。选择、展开和 `scrollToRow` 都用它。
+
+## RAC-TABLE-ID
+
+`AutoTable` 的 `id` 是空的，设置会写到 `${namespace}:table:`。仅开发警告。
+
+修复：每张表传一个稳定的 id。
+
+## RAC-COLUMN-COMPONENT
+
+列的 `component` 未在 `AutoConfigProvider` 的 `config.columns` 中注册时，开发模式警告 `RAC-COLUMN-COMPONENT`，单元格使用默认格式。注册该键，或在列上提供 `render`、`format`、`sort`；列上的函数优先。
+
+## RAC-ROW-ACTION
+
+行菜单动作缺少 `onClick`，且 `action` 不是已注册的 `config.rowActions` 键时，选择该动作会在状态行显示 `RAC-ROW-ACTION`。提供 `onClick` 或注册对应的 `action`；两者都有时 `onClick` 优先。
+
+## RAC-TABLE-SOURCE
+
+`source` 是 `AutoConfigProvider` 的 `config.sources` 中的数据源键。未知键会显示 `RAC-TABLE-SOURCE` 和重试按钮。注册该键，或改用 `data` / `dataSource`；三者只能提供一个。
+
+## RAC-TABLE-FILTER
+
+设置里的筛选 JSON 不是合法查询。界面仍显示翻译后的 "Invalid filter"，并保留上一次的筛选。
+
+修复：分组是 `{ kind: "group", operator: "and" | "or", children }`。条件是 `{ kind: "condition", field, operator, value }`，`field` 必须是列键。`between` 的值是 `[from, to]`。`in` 的值是数组。
+
+## RAC-QUERY-FIELD
+
+`serializeRsql` 拒绝了不符合 `/^[\w.]+$/` 的字段名。
+
+修复：只用字母、数字、下划线和点。先重命名或映射列，再序列化。
+
+## RAC-DIALOG-PROVIDER
+
+在 `AutoDialogProvider` 之外调用了 `useAutoDialog()`。
+
+修复：在该树外包一层 `<AutoDialogProvider>`。`AutoConfigProvider` 不提供弹窗，而且是可选的。声明式 `<AutoDialog open>` 不用这个 hook。

package/docs/i18n/zh-TW/README.md

@@ -12,10 +12,14 @@
 
 ## 專案狀態
 
-目前版本為 0.1.2,API 仍可能變動。需要 React 19。本套件提供 ESM 與 TypeScript 型別宣告。內建介面文字預設為中文,可透過 AutoConfigProvider.config.t 進行翻譯。
+目前版本為 0.1.3,API 仍可能變動。需要 React 19。本套件提供 ESM 與 TypeScript 型別宣告。內建介面文字預設為英文,可透過 AutoConfigProvider.config.t 進行翻譯。
 
 使用 `pnpm add @zeroman.yang/react-auto-components` 安裝（npm、yarn 同樣可用）。peer dependency 為 React 19 與 react-dom 19。請在入口引入一次樣式：`import "@zeroman.yang/react-auto-components/style.css"`。
 
+在應用程式入口引入一次 `import "@zeroman.yang/react-auto-components/style.css"`。缺少樣式時，開發模式警告 `RAC-CSS-MISSING`。
+
+XLSX 匯出缺少 `exportXlsx` 配接器時為 `RAC-TABLE-XLSX`；無法載入選用相依套件 `exceljs` 時為 `RAC-XLSX-DEP`。從 `@zeroman.yang/react-auto-components/xlsx` 匯入並傳入配接器，按需執行 `pnpm add exceljs`。CSV 與 JSON 不需要它。
+
 - [線上示範 (GitHub Pages)](https://zeroman.github.io/react-auto-components/)
 - [貢獻指南](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/zh-TW/CONTRIBUTING.md)
 - [變更紀錄](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/zh-TW/CHANGELOG.md)
@@ -99,7 +103,7 @@ t 回呼會接收訊息鍵值與後備文字。翻譯內建訊息時請保留 {0
 | 元件 | 功能 |
 | --- | --- |
 | AutoForm | 原生欄位型別、選項虛擬化、連動選擇、上傳介接器、自訂繪製、相依欄位、條件式顯示、非同步驗證、受控狀態、失敗後保留輸入 |
-| AutoSearchPanel | 基本／進階條件、手動／即時搜尋、重設、排序標籤、共用查詢 AST 和 RSQL 序列化 |
+| AutoSearch | 基本／進階條件、手動／即時搜尋、重設、排序標籤、共用查詢 AST 和 RSQL 序列化 |
 | AutoTable | 本機／遠端資料、多欄排序、欄位篩選、分頁、穩定的選取狀態、虛擬化、樹狀／詳細資料展開、彙總、合併儲存格、CRUD、快顯功能表和複製 |
 | AutoDialog | 宣告式／命令式 API、隔離的 Provider、草稿、關閉防護、焦點管理、拖曳、全螢幕和非同步提交 |
 | AutoTabs | 水平／垂直版面、巢狀結構、權限、停用分頁、保留面板狀態和重新整理 |
@@ -215,3 +219,5 @@ pnpm test:e2e
 AutoChat 提供輕量的對話版面，具備串流跟隨、歷史載入與輸入區。供應 React 內容或 renderMessage 來渲染訊息，無需額外的執行時相依套件。
 
 [AutoChat API](auto-chat.md)
+
+回呼拋錯之後元件會怎樣，見行為契約：[AutoForm](auto-form.md)、[AutoSearch](auto-search.md)、[AutoTable](auto-table.md)、[AutoDialog](auto-dialog.md)、[AutoTabs](auto-tabs.md)、[AutoMenu](auto-menu.md)。開發者錯誤碼：[errors.md](errors.md)。

package/docs/i18n/zh-TW/auto-dialog.md

@@ -0,0 +1,64 @@
+# AutoDialog
+
+[English](../../auto-dialog.md) | [简体中文](../zh-CN/auto-dialog.md) | **繁體中文** | [日本語](../ja/auto-dialog.md) | [한국어](../ko/auto-dialog.md) | [Español](../es/auto-dialog.md) | [Français](../fr/auto-dialog.md) | [Deutsch](../de/auto-dialog.md) | [Português (Brasil)](../pt-BR/auto-dialog.md) | [Русский](../ru/auto-dialog.md)
+
+模態彈窗。可以宣告式（`<AutoDialog open>`），也可以命令式（`useAutoDialog().open()`）。傳入 `fields` 會渲染 [AutoForm](auto-form.md)。不傳欄位時渲染 `content`。
+
+## 用法
+
+```tsx
+import {
+  AutoDialogProvider,
+  useAutoDialog,
+} from "@zeroman.yang/react-auto-components";
+import "@zeroman.yang/react-auto-components/style.css";
+
+function EditButton() {
+  const dialog = useAutoDialog();
+  return (
+    <button
+      onClick={() =>
+        dialog.open({
+          title: "編輯",
+          fields: [{ name: "name", label: "姓名", required: true }],
+          onSubmit: async (values) => save(values),
+        })
+      }
+    >
+      編輯
+    </button>
+  );
+}
+
+<AutoDialogProvider>
+  <EditButton />
+</AutoDialogProvider>
+```
+
+在 provider 外呼叫 `useAutoDialog()` 會拋 `RAC-DIALOG-PROVIDER`。宣告式 `<AutoDialog open onOpenChange>` 不需要 provider。
+
+## 行為與屬性
+
+| 屬性 | 行為 |
+| --- | --- |
+| `open`、`onOpenChange` | 僅宣告式。`onOpenChange(false)` 走關閉流程。 |
+| `fields` | 正文裡的 schema 表單。校驗規則與 AutoForm 相同。 |
+| `content` | 沒有 `fields` 時使用。 |
+| `onSubmit(values)` | 校驗通過後呼叫。**reject 或 throw：彈窗保持開啟，顯示 `error.message`，值保留。** resolve 後仍會走 `beforeClose`。 |
+| `beforeClose(reason)` | `reason` 為 `"submit"`、`"cancel"` 或 `"close"`。**返回 `false` 則保持開啟。throw 也保持開啟並顯示訊息。** |
+| `onClose(reason)` | 只有真正關掉之後才呼叫。 |
+| `draftKey` | 草稿存在 `${namespace}:draft:${draftKey}`，成功提交後刪除。不傳則不儲存。 |
+| `showReset` | 顯示錶單重置。 |
+| `hideFooter` | 隱藏預設的確認/取消。用 `footer` 自己畫。 |
+| `draggable` | 拖標題欄。全屏時忽略。 |
+| `width` | 畫素。預設 `560`。 |
+| `fullscreen` | 初始全屏。標題欄按鈕可切換。 |
+| `size` | 回落到 provider 的尺寸。預設 `"medium"`。 |
+
+`useAutoDialog().open()` 返回的 `close()` 在 `beforeClose` 攔住時 resolve `false`。
+
+命令式彈窗可以疊多層。每次 `open()` 返回 `{ id, close }`。`close(id)` 關掉對應的一層。
+
+## 前置條件
+
+入口引入一次 `style.css`。`AutoConfigProvider` 可選。它的 `namespace` 會進入 `draftKey` 的儲存鍵，`t` 翻譯內建按鈕。它不能代替 `AutoDialogProvider`。