@zeroman.yang/react-auto-components 0.1.0

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

@@ -0,0 +1,217 @@
+# React Auto Components
+
+[English](../../../README.md) | **简体中文** | [繁體中文](../zh-TW/README.md) | [日本語](../ja/README.md) | [한국어](../ko/README.md) | [Español](../es/README.md) | [Français](../fr/README.md) | [Deutsch](../de/README.md) | [Português (Brasil)](../pt-BR/README.md) | [Русский](../ru/README.md)
+
+一个独立的、以 schema 驱动的 React 19 组件库，覆盖表单、表格与对话。基于 TypeScript、TanStack Table 9 / Form / Virtual、Radix 和 Floating UI 构建，不依赖 Ant Design、Element Plus 或 MUI。库构建使用 React Compiler。
+
+[![Auto Studio 演示截图](../../assets/demo.png)](https://zeroman.github.io/react-auto-components/)
+
+<p align="center">
+  <a href="https://zeroman.github.io/react-auto-components/"><strong>🚀 在线演示 (GitHub Pages)</strong></a> · <a href="#演示与独立测试项目">本地运行</a> · <a href="#组件">组件列表</a>
+</p>
+
+## 项目状态
+
+当前版本为 0.1.0，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"`。
+
+- [在线演示 (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)
+- [注册账号与发布指南](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/zh-CN/publishing.md)
+- [MIT 许可证](../../../LICENSE)
+
+## 演示与独立测试项目
+
+可以在浏览器中直接访问 **[GitHub Pages 在线演示](https://zeroman.github.io/react-auto-components/)**。
+
+本地运行与开发（需要 Node.js >= 22.12 与 pnpm 12.5）：
+
+```sh
+pnpm install --frozen-lockfile
+pnpm prepare:test-project
+pnpm --dir test-project dev
+```
+
+打开 http://127.0.0.1:4173 。测试项目提供七个组件页面、本地/服务端/万行/树形表格、CRUD、提交失败重试、草稿、嵌套标签及动态行高场景。
+
+演示会自动检测浏览器语言，并以英语作为回退。可以从页眉或全局设置中选择语言；所选语言在重新加载后仍会保留。选择“自动”可重新跟随浏览器语言。支持十种语言。页面填满整个视口，表格和较长的面板在其自身区域内滚动。
+
+每个示例页面都提供**查看代码**按钮，会在弹窗中打开该示例的真实源码文件，支持文件切换、一键复制和跳转 GitHub。
+
+`test-project` 有独立 package.json 和 lockfile，安装 `pnpm pack` 的真实产物，没有源代码别名。修改组件库后重新运行 `pnpm prepare:test-project`；脚本使用内容哈希文件名更新依赖，避免同名 tarball 缓存。
+
+### 自动化更新与可复用命令
+
+修改组件或示例后，可一键完成自动化编译与截图刷新：
+
+```sh
+pnpm demo:update       # 一键更新：编译库、更新测试工程、打包 demo 静态文件并自动截取最新界面
+pnpm demo:build        # 仅编译 demo 静态产物至 demo-dist（适配 GitHub Pages）
+pnpm demo:screenshot   # 仅通过无头 Chromium 重新截取 docs/assets/demo.png
+```
+
+代码推送到 `main` 分支时，GitHub Actions 会自动触发构建并部署静态文件到 GitHub Pages。
+
+## 接入
+
+```tsx
+import { useState } from 'react';
+import {
+  AutoConfigProvider, AutoDialogProvider, AutoTable,
+  type AutoColumn, type Field,
+} from '@zeroman.yang/react-auto-components';
+import '@zeroman.yang/react-auto-components/style.css';
+
+type Person = { id: number; name: string; enabled: boolean };
+const columns: AutoColumn<Person>[] = [
+  { key: 'name', label: '姓名', sortable: true },
+  { key: 'enabled', label: '已启用', options: [
+    { label: '是', value: true }, { label: '否', value: false },
+  ] },
+];
+const fields: Field<Person>[] = [
+  { name: 'name', label: '姓名', required: true },
+  { name: 'enabled', label: '已启用', type: 'switch', defaultValue: true },
+];
+export function App() {
+  const [rows, setRows] = useState<Person[]>([]);
+  return <AutoConfigProvider config={{ namespace: 'my-app' }}>
+    <AutoDialogProvider>
+      <AutoTable<Person> id="people" rowKey="id" data={rows}
+        columns={columns} formFields={fields} searchFields={fields}
+        onAdd={value => setRows(old => [...old, { ...value, id: Date.now() }])}
+        onEdit={(row, value) => setRows(old => old.map(item => item.id === row.id ? { ...row, ...value } : item))}
+        onDelete={selected => setRows(old => old.filter(item => !selected.some(row => row.id === item.id)))}
+      />
+    </AutoDialogProvider>
+  </AutoConfigProvider>;
+}
+```
+
+字段、列与 ref 使用泛型；类型错误的字段名或默认值会在编译期报错。Provider 提供命名空间、权限、字段翻译、自定义字段、通知和持久化适配。 内置标签、校验消息和无障碍文本使用 AutoConfigProvider.config.t；显式指定的组件标签优先。
+
+t 回调接收一个消息键和一个回退文本。在翻译内置消息时，请保留诸如 {0} 和 {1} 的编号占位符；组件会在翻译后替换这些占位符的值。
+
+## 组件
+
+| 组件 | 主要能力 |
+| --- | --- |
+| AutoForm | 多种原生字段、虚拟选项、级联、上传适配、自定义渲染、联动、动态显隐、异步规则、受控状态、失败保留输入 |
+| AutoSearchPanel | 基本/更多条件、手动/即时查询、重置、排序标签、统一查询 AST 与 RSQL 序列化 |
+| AutoTable | 本地/远程数据、多列排序、列筛选、分页、稳定选择、虚拟化、树形/详情展开、汇总、合并单元格、CRUD、右键菜单、复制 |
+| AutoDialog | 声明式/命令式、隔离的 Provider、草稿、关闭拦截、焦点管理、拖动、全屏、异步提交 |
+| AutoTabs | 横向/纵向、嵌套、权限、禁用、保留面板状态、刷新 |
+| AutoMenu | 侧边导航，支持图标、描述、徽标、嵌套分组、权限与可折叠图标栏 |
+| AutoChat | 调用方自定义消息渲染、可选虚拟化、流式跟随、锚定历史加载、发送/停止输入框与自定义操作 |
+
+表格布局、排序、筛选、导出各自支持命名方案及版本。默认 localStorage 持久化，也可注入远程适配器。JSON/CSV 内置；XLSX 使用可选的独立适配器：
+
+```tsx
+import { exportXlsx } from '@zeroman.yang/react-auto-components/xlsx';
+// <AutoTable ... exportXlsx={exportXlsx} />
+```
+
+ExcelJS 在首次使用适配器时动态加载，不进入库的主入口。纯 CSV/JSON 用户可安装时省略 optional dependencies。
+
+## 验证
+
+```sh
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm prepare:test-project
+pnpm --dir test-project build
+pnpm exec playwright install chromium  # 仅首次运行
+pnpm test:e2e
+```
+
+单元测试覆盖字段、异步校验、查询、弹窗、虚拟化、表格、配置迁移与导出。Playwright 从已打包的公开入口测试交互，桌面/手机截图写入 `test-project/test-results`。
+
+## 行为约定
+
+- 这是 React 原生 API，不是旧 Vue 属性/方法的逐项兼容层。见 [迁移指南](migration.md)。
+- 数据由业务持有。CRUD 回调负责保存，失败抛错可保留编辑；成功后组件刷新远程数据。本地数据需由调用方更新。
+- 表格 `id` 在命名空间内唯一，`rowKey` 在所有分页和树节点内唯一。服务端模式显式传 `columns`，总数由数据源返回。
+- `query` / `value` 受控时由父组件接收回调并更新；普通使用可省略。
+- 启用合并单元格后使用非虚拟语义表格，适合分页数据；避免跨虚拟窗口的 rowSpan 错位。
+- 服务端全量筛选汇总由 `summaryValues` 提供；未提供的汇总显示 `—`，不会把当前页合计冒充全量合计。`summaryScope="page"` 可显式计算当前页。
+- 上传进行中暂停提交；重置、替换字段值和卸载会取消旧上传，晚到结果不会覆盖新值。
+- 远程“全部筛选结果”导出会逐页请求数据源；大规模业务可自行实现后台导出。
+- 浏览器样式通过 `style.css` 显式导入；JS 模块可在无 window 的 Node 环境导入。
+
+## AutoTable 占满剩余高度
+
+`height={440}` 继续表示数据滚动区的固定高度。使用 `height="auto"` 时，整个表格填满父布局分配的高度，搜索区、工具栏与分页按实际内容布局，数据区使用剩余空间并独立滚动：
+
+```tsx
+<div style={{ height: '100dvh', display: 'flex', flexDirection: 'column', gap: 12 }}>
+  <header>页面标题和描述</header>
+  <AutoTable<Person> id="people" rowKey="id" data={rows}
+    columns={columns} height="auto" />
+  <footer>页面页脚</footer>
+</div>
+```
+
+父容器必须有可确定的高度。嵌套 Flex 容器使用 `flex: 1; min-height: 0` 传递剩余空间；Grid 可使用 `grid-template-rows: auto minmax(0, 1fr) auto`。不需要 JS 计算视口减去工具栏高度；搜索条件增减、工具栏换行及父容器尺寸变化由布局自动处理，虚拟列表跟随实际滚动区尺寸。
+
+这与“随数据条数撑高表格”不同：空数据和少量数据仍填满剩余空间。父容器至少应能容纳搜索区、工具栏及分页本身。
+
+测试项目在 **AutoTable → 剩余高度** Tab 内演示，保留侧栏和页面顶部；旧地址 `http://127.0.0.1:4173/?demo=auto-height` 会直接选中该 Tab。对应浏览器测试：`test-project/tests/auto-height.spec.ts`。
+
+## 全局表单布局
+
+通过 `AutoConfigProvider.config.form` 统一控制普通表单、搜索区、表格搜索区和弹窗表单。支持上方标签与左侧标签两种布局，标签文字可独立设置左对齐或右对齐；未配置时，库默认使用上方标签和舒适间距。
+
+```tsx
+<AutoConfigProvider config={{
+  form: {
+    labelPosition: 'left', // 'top'：位于上方；'left'：位于控件左侧
+    labelAlign: 'right',   // 文本右对齐；标签保持在控件左侧
+    labelWidth: 80,
+    density: 'compact',   // 'comfortable'：间距更大
+  },
+}}>
+  <App />
+</AutoConfigProvider>
+```
+
+嵌套 Provider 按属性合并布局，组件显式参数优先于所在 Provider。例如，在全局同行布局中保留某个表单的上下排列：
+
+```tsx
+<AutoForm fields={fields} labelPosition="top" density="comfortable" />
+<AutoTable id="people" rowKey="id" data={rows} columns={columns}
+  searchFields={searchFields}
+  searchLayout={{ labelWidth: 100, columns: 3 }} />
+```
+
+`labelWidth` 默认为 `"auto"`，也接受像素数或 CSS 宽度（例如 `"6em"`）。自动模式下，搜索项的标签分别贴合文字；普通表单和弹窗表单按可见标签统一宽度，保持控件对齐。长标签最多占字段宽度的 45%，超出时换行，为输入控件保留空间；显式固定宽度不受此自动限制。紧凑搜索区在宽度足够时将操作按钮放在同一行，窄屏自动换行。标签关联保留，错误提示和说明跟随控件对齐，长标签可以折行。
+
+演示项目通过侧栏 **全局设置** 或右上角齿轮打开独立设置面板，统一修改布局、密度、标签宽度和主题；设置即时生效，不清空当前示例的输入；表单页还可选择 **跟随全局** 或局部覆盖。演示项目通过 Provider 显式启用同行紧凑布局。
+
+## 全局尺寸与密度
+
+`AutoConfigProvider` 支持 `size: "small" | "medium" | "large"` 和 `density: "compact" | "comfortable"`。组件显式参数优先于对应类别配置，类别配置优先于全局值：
+
+```tsx
+<AutoConfigProvider config={{
+  size: "medium",
+  density: "compact",
+  form: { labelPosition: "left", labelAlign: "right" },
+  table: { density: "compact" },
+  tabs: { density: "compact" },
+}}>
+  <AutoForm fields={fields} size="small" />
+</AutoConfigProvider>
+```
+
+表格密度另外支持 `normal`（标准）。表格设置面板的默认项为“跟随全局”；选择紧凑、标准或宽松会覆盖全局密度并随布局方案保存，组件 `density` 参数优先级最高。嵌套组件的局部尺寸独立生效。
+
+表单支持 `resetLabel`、`extraActions` 和 `onReset`；搜索面板支持 `searchLabel`、`resetLabel` 和 `extraActions`；弹窗支持 `cancelLabel` 与 `extraActions`。`AutoTabs` 的条目可配置 `badge`；`AutoTable.empty` 可自定义无数据内容。
+
+### AutoChat
+
+AutoChat 提供轻量的对话布局，支持流式跟随、历史消息加载和消息输入框。传入 React 内容或 renderMessage 即可渲染消息，无需额外的运行时依赖。
+
+[AutoChat API](auto-chat.md)

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

@@ -0,0 +1,82 @@
+# AutoChat
+
+[English](../../auto-chat.md) | **简体中文** | [繁體中文](../zh-TW/auto-chat.md) | [日本語](../ja/auto-chat.md) | [한국어](../ko/auto-chat.md) | [Español](../es/auto-chat.md) | [Français](../fr/auto-chat.md) | [Deutsch](../de/auto-chat.md) | [Português (Brasil)](../pt-BR/auto-chat.md) | [Русский](../ru/auto-chat.md)
+
+提供可选输入框、流式跟随与更早历史加载的对话布局。AutoChat 不新增运行时依赖，也不会发起网络请求、持久化消息、解析 Markdown、执行工具输出或渲染原始 HTML。
+
+## 用法
+
+```tsx
+import { useState } from "react";
+import { AutoChat, type AutoChatMessage } from "@zeroman.yang/react-auto-components";
+import "@zeroman.yang/react-auto-components/style.css";
+
+export function Conversation() {
+  const [messages, setMessages] = useState<AutoChatMessage[]>([]);
+  return (
+    <AutoChat
+      height={600}
+      messages={messages}
+      onSend={async (text) => {
+        setMessages((current) => [
+          ...current,
+          { id: crypto.randomUUID(), role: "user", content: text },
+        ]);
+        // 在这里调用你的服务并更新 messages。
+      }}
+    />
+  );
+}
+```
+
+## 自带渲染器
+
+将 React 节点作为 `content` 传入，或用应用自有字段扩展 `AutoChatMessage` 并提供 `renderMessage(message, { index })`。在这里接入既有的 Markdown 渲染器、代码查看器、附件卡片或工具结果组件。AutoChat 不解释这些格式；纯字符串按文本渲染。宿主渲染器负责链接、HTML 与所有交互内容。
+
+每条消息都有稳定唯一的 `id` 与 `role`：`user`、`assistant`、`system`、`tool` 或 `error`。可选的 `author`、`avatar`、`meta` 与 `streaming` 自定义消息外壳；`renderActions(message, context)` 提供消息操作。流式回复更新时保持同一 ID，并以不可变方式替换 messages 数组。
+
+## 行为与属性
+
+| 属性 | 行为 |
+| --- | --- |
+| `height` | CSS 高度，默认 `100%`。为父容器给定高度，或传数字如 `600`。历史记录在组件内部滚动。 |
+| `autoFollow` | 默认 `true`。跟随底部的新内容与高度变化；读者上滚时暂停。**回到最新** 恢复跟随。 |
+| `hasMore`, `onLoadOlder`, `loadingOlder` | 显示更早历史按钮。以稳定 ID 前插消息；可见消息保持锚定。请求会去重，失败的请求可重试。 |
+| `onSend(text)` | 启用输入框。接收原始非空文本；可返回 Promise。接受则清空草稿；拒绝则保留草稿并显示通用错误。较新的草稿不会被较旧的发送清空。 |
+| `value`, `defaultValue`, `onValueChange` | 受控或本地输入框内容。使用受控值时由宿主应用变更。 |
+| `generating`, `onStop` | 生成期间禁用发送并提供停止按钮。宿主必须自行取消流/请求并更新 `generating`。 |
+| `sendOnEnter` | 默认 `true`；Shift+Enter 换行。输入法组合事件与确认键不会提交。设为 `false` 仅按钮发送。 |
+| `disabled`, `composer` | 禁用内置编辑器，或在使用外部编辑器时隐藏（`composer={false}`）。 |
+| `conversationKey` | 切换会话时重置本地草稿、进行中 UI 与滚动。受控值与取消仍由宿主管理。 |
+| `header`, `footer`, `empty`, `composerExtra` | React 内容插槽。 |
+| `size`, `density` | 覆盖全局 `AutoConfigProvider` 设置。 |
+| `labels` | 覆盖内置英文文案。Provider 也会翻译 `chat.send`、`chat.latest` 等 `chat.*` 键。 |
+| `onSendError`, `onLoadError` | 接收原始错误用于应用日志；内部错误详情不会自动展示。 |
+
+大量历史记录时设置 `virtual`，复用包内既有的 TanStack Virtual 依赖。只有可见消息与少量 overscan 窗口会挂载，动态行高会被测量。必要时调整 `estimatedMessageHeight`（默认 `120`）与 `overscan`（默认 `6`）。前插历史时保持消息 ID 稳定。虚拟模式下，需要跨行卸载存续的交互状态请保存在宿主中。普通会话默认使用非虚拟布局。
+
+**大历史** 演示加载 1,000、10,000 或 50,000 条可变高度消息，上报实际挂载消息数，并支持追加 100 条、流式、加载更早历史与跳转到任一端。
+
+`AutoChatHandle` ref 暴露 `scrollToBottom()`、`scrollToMessage(id)`（返回 ID 是否存在）、`focusComposer()` 与 `getScrollElement()`。历史区域使用可键盘聚焦的日志；独立的状态区播报发送/生成状态，不会播报每个流式 token。
+
+本地流式模拟、取消、自定义工具卡片、分页、发送失败与十语言 UI 见[可运行演示](../../../test-project/src/examples/ChatDemo.tsx)。
+
+## 演示中的富渲染
+
+私有 `test-project` 安装了 [react-markdown](https://github.com/remarkjs/react-markdown) 与 [remark-gfm](https://github.com/remarkjs/remark-gfm)。这些依赖不属于组件库。格式选择器可插入 Markdown（标题、强调、任务列表与 GFM 表格）、代码、JSON、数据表、本地图片或可交互的 React 评审卡片。
+
+`ChatRenderers.tsx` 根据结构化消息数据选择 React 组件；`ChatTaskCard.tsx` 演示本地交互状态。Markdown 使用 `skipHtml` 与库默认的 URL 处理，不会编译 JSX 或执行代码块。同一个 Markdown 渲染器也展示流式回复。自定义组件由应用提供，不会从可执行消息文本实例化。
+
+```tsx
+import Markdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+<AutoChat
+  messages={messages}
+  renderMessage={(message) => (
+    <Markdown remarkPlugins={[remarkGfm]} skipHtml>
+      {String(message.content ?? "")}
+    </Markdown>
+  )}
+/>
+```

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

@@ -0,0 +1,71 @@
+# 组件接入指南
+
+[English](../../migration.md) | **简体中文** | [繁體中文](../zh-TW/migration.md) | [日本語](../ja/migration.md) | [한국어](../ko/migration.md) | [Español](../es/migration.md) | [Français](../fr/migration.md) | [Deutsch](../de/migration.md) | [Português (Brasil)](../pt-BR/migration.md) | [Русский](../ru/migration.md)
+
+通过 React 泛型、回调和 Provider 来配置组件。下表将常见的应用需求映射到对应的公开 API 与可运行示例。
+
+| 原场景 | React 接口 | 可运行示例/测试 |
+| --- | --- | --- |
+| 表单字段与 v-model | `fields: Field<T>[]`、`value/onChange` 或 `defaultValue` | `test-project/src/examples/FormDemo.tsx` 表单页；`tests/form*.test.tsx` |
+| 插槽、追加内容 | 字段 `render`、列 `render/header`、ReactNode | 表单/表格页 |
+| 表单实例操作 | `ref.validate/reset/getValues/setValue/focus` | `tests/form.test.tsx` |
+| 搜索、关联条件、RSQL | `buildQuery`、`matchesQuery`、`serializeRsql` | 搜索页；`tests/query.test.ts` |
+| 表格本地/接口数据 | `data` 或 `dataSource(query,{signal})`，二选一 | 表格页；`tests/table.test.tsx` |
+| 布局/筛选/排序/导出方案 | 设置弹窗中的独立方案，`versions` 分别失效 | 表格页；`tests/table-settings.test.ts` |
+| 树、详情、汇总、合并 | `getChildren/renderExpanded`、列 `summary/merge` | 树形与展开场景；`tests/table-advanced.test.tsx` |
+| 新增、修改、删除 | `formFields` 与 `onAdd/onEdit/onDelete` | 浏览器 CRUD 用例 |
+| 命令式弹窗 | `AutoDialogProvider` + `useAutoDialog().open()` | 弹窗页；`tests/dialog.test.tsx` |
+| 标签及嵌套标签 | `AutoTabs` items、value/onChange、keepMounted | 标签页；`tests/tabs.test.tsx` |
+| 聊天消息列表与会话界面 | `AutoChat`、`messages`、`onSend`、`renderMessage` | `test-project/src/examples/Chat*.tsx` 聊天页面；`tests/chat.test.tsx` |
+
+## 字段类型
+
+`input/email/textarea/integer/float/percentage/progress/switch/select/select-v2/radio/checkbox/cascader/autocomplete/date/datetime/daterange/datetimerange/upload/text/title/tip/button/append/custom`。
+
+`select-v2` 使用虚拟选项；范围日期使用两个有独立标签的原生输入；日期值通过 `dateValue` 选择字符串或时间戳。数字输入允许编辑中间态，提交时应使用字段规则验证业务约束。`rules` 支持异步校验，隐藏字段跳过校验。选项保留数字/布尔值，不强制转字符串。
+
+```tsx
+const fields: Field<User>[] = [
+  { name: 'name', label: '姓名', required: true },
+  { name: 'note', label: '备注', hidden: values => !values.enabled,
+    render: ({ value, onChange, disabled }) =>
+      <textarea disabled={disabled} value={String(value ?? '')}
+        onChange={event => onChange(event.target.value)} /> },
+];
+```
+
+完整参数以导出的 TypeScript 类型为准。`Field<T>` 绑定 T 的实际键；标题、提示等结构项无需绑定数据属性。
+
+## 服务端数据源
+
+```tsx
+const dataSource: DataSource<User> = async (query, { signal }) => {
+  const response = await fetch('/api/users/search', {
+    method: 'POST', signal,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(query),
+  });
+  if (!response.ok) throw new Error('加载失败');
+  return response.json(); // { rows: User[], total: number }
+};
+```
+
+页码从 0 开始；`sort` 是多字段顺序数组，`filter` 是结构化查询树。组件取消旧请求，并阻止晚到结果覆盖新查询。业务条件在数据源闭包外变化时调用表格 `ref.refresh()`；保持数据源函数稳定可避免不必要请求。RSQL 适配仅用于后端协议需要时，不执行查询字符串。
+
+## 业务上传与持久化
+
+字段 `upload(files, signal)` 返回业务保存后的字段值，组件展示上传失败；上传 URL、鉴权与对象存储策略由调用方提供。
+
+```tsx
+<AutoConfigProvider config={{
+  namespace: 'tenant-admin',
+  canAccess: access => !access.permissions?.length || access.permissions.every(p => myPermissions.includes(p)),
+  settings: {
+    load: key => api.loadTableSettings(key),
+    save: (key, settings) => api.saveTableSettings(key, settings),
+  },
+  notify: (message, level) => showToast(message, level),
+}}>{children}</AutoConfigProvider>
+```
+
+本地更改会立即生效；远程保存按串行方式执行，失败后可选择重试。当更改持久化设置的格式时，请使用新的表格 id 或版本号，以避免加载不兼容的设置。

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

@@ -0,0 +1,217 @@
+# React Auto Components
+
+[English](../../../README.md) | [简体中文](../zh-CN/README.md) | **繁體中文** | [日本語](../ja/README.md) | [한국어](../ko/README.md) | [Español](../es/README.md) | [Français](../fr/README.md) | [Deutsch](../de/README.md) | [Português (Brasil)](../pt-BR/README.md) | [Русский](../ru/README.md)
+
+獨立、以 schema 驅動的 React 19 元件庫，涵蓋表單、表格與對話。以 TypeScript、TanStack Table 9 / Form / Virtual、Radix 與 Floating UI 建構,不使用 Ant Design、Element Plus 或 MUI。函式庫建置採用 React Compiler。
+
+[![Auto Studio 示範截圖](../../assets/demo.png)](https://zeroman.github.io/react-auto-components/)
+
+<p align="center">
+  <a href="https://zeroman.github.io/react-auto-components/"><strong>🚀 線上示範 (GitHub Pages)</strong></a> · <a href="#示範與獨立測試專案">本機執行</a> · <a href="#元件">元件列表</a>
+</p>
+
+## 專案狀態
+
+目前版本為 0.1.0,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"`。
+
+- [線上示範 (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)
+- [帳號設定與發佈](https://github.com/Zeroman/react-auto-components/blob/main/docs/i18n/zh-TW/publishing.md)
+- [MIT 授權條款](../../../LICENSE)
+
+## 示範與獨立測試專案
+
+可在瀏覽器中直接開啟 **[線上示範](https://zeroman.github.io/react-auto-components/)**。
+
+本機執行與開發（需要 Node.js >= 22.12 和 pnpm 12.5）：
+
+```sh
+pnpm install --frozen-lockfile
+pnpm prepare:test-project
+pnpm --dir test-project dev
+```
+
+開啟 http://127.0.0.1:4173。測試專案包含全部七個元件的頁面，以及本機／伺服器端／10,000 筆資料／樹狀表格、CRUD、提交失敗重試、草稿、巢狀分頁和動態列高範例。
+
+示範會自動偵測瀏覽器語言,並以英文作為後備。可從頁首或全域設定中選擇語言;所選語言會在重新載入後保留。選擇 Auto 即可再次跟隨瀏覽器語言。支援十種語言。頁面會填滿整個視區,表格與較長的面板會在其自身區域內捲動。
+
+每個範例頁面都提供**檢視原始碼**按鈕，會在彈窗中開啟該範例的真實原始碼檔案，支援檔案切換、一鍵複製與前往 GitHub。
+
+`test-project` 有自己的 package.json 和鎖定檔。它安裝 `pnpm pack` 的實際輸出，不使用原始碼別名。修改元件庫後，請再次執行 `pnpm prepare:test-project`；指令碼使用包含內容雜湊的檔名，避免沿用過期的 tarball 快取。
+
+### 自動化更新與可重複使用指令
+
+修改元件或範例後，可一鍵完成自動化編譯與截圖更新：
+
+```sh
+pnpm demo:update       # 完整更新：建置元件庫、更新測試專案、打包 demo 靜態檔案並自動截取最新畫面
+pnpm demo:build        # 僅編譯 demo 靜態產物至 demo-dist（適配 GitHub Pages）
+pnpm demo:screenshot   # 僅透過無周邊 Chromium 重新截取 docs/assets/demo.png
+```
+
+程式碼推送到 `main` 分支時，GitHub Actions 會自動建置並部署靜態檔案至 GitHub Pages。
+
+## 使用方式
+
+```tsx
+import { useState } from 'react';
+import {
+  AutoConfigProvider, AutoDialogProvider, AutoTable,
+  type AutoColumn, type Field,
+} from '@zeroman.yang/react-auto-components';
+import '@zeroman.yang/react-auto-components/style.css';
+
+type Person = { id: number; name: string; enabled: boolean };
+const columns: AutoColumn<Person>[] = [
+  { key: 'name', label: '姓名', sortable: true },
+  { key: 'enabled', label: '已啟用', options: [
+    { label: '是', value: true }, { label: '否', value: false },
+  ] },
+];
+const fields: Field<Person>[] = [
+  { name: 'name', label: '姓名', required: true },
+  { name: 'enabled', label: '已啟用', type: 'switch', defaultValue: true },
+];
+export function App() {
+  const [rows, setRows] = useState<Person[]>([]);
+  return <AutoConfigProvider config={{ namespace: 'my-app' }}>
+    <AutoDialogProvider>
+      <AutoTable<Person> id="people" rowKey="id" data={rows}
+        columns={columns} formFields={fields} searchFields={fields}
+        onAdd={value => setRows(old => [...old, { ...value, id: Date.now() }])}
+        onEdit={(row, value) => setRows(old => old.map(item => item.id === row.id ? { ...row, ...value } : item))}
+        onDelete={selected => setRows(old => old.filter(item => !selected.some(row => row.id === item.id)))}
+      />
+    </AutoDialogProvider>
+  </AutoConfigProvider>;
+}
+```
+
+欄位、資料行和 ref 使用泛型：無效的欄位名稱或預設值會產生編譯期錯誤。Provider 支援命名空間、權限、欄位標籤翻譯、自訂欄位、通知和持久化介接器。 內建標籤、驗證訊息與無障礙文字皆使用 AutoConfigProvider.config.t;明確指定的元件標籤具有較高優先順序。
+
+t 回呼會接收訊息鍵值與後備文字。翻譯內建訊息時請保留 {0}、{1} 等編號佔位符;元件會在翻譯之後代入其值。
+
+## 元件
+
+| 元件 | 功能 |
+| --- | --- |
+| AutoForm | 原生欄位型別、選項虛擬化、連動選擇、上傳介接器、自訂繪製、相依欄位、條件式顯示、非同步驗證、受控狀態、失敗後保留輸入 |
+| AutoSearchPanel | 基本／進階條件、手動／即時搜尋、重設、排序標籤、共用查詢 AST 和 RSQL 序列化 |
+| AutoTable | 本機／遠端資料、多欄排序、欄位篩選、分頁、穩定的選取狀態、虛擬化、樹狀／詳細資料展開、彙總、合併儲存格、CRUD、快顯功能表和複製 |
+| AutoDialog | 宣告式／命令式 API、隔離的 Provider、草稿、關閉防護、焦點管理、拖曳、全螢幕和非同步提交 |
+| AutoTabs | 水平／垂直版面、巢狀結構、權限、停用分頁、保留面板狀態和重新整理 |
+| AutoMenu | 側邊導覽，支援圖示、描述、徽章、巢狀分組、權限與可折疊圖示欄 |
+| AutoChat | 呼叫端自訂訊息渲染、可選虛擬化、串流跟隨、錨定歷史載入、傳送／停止輸入框與自訂操作 |
+
+表格版面、排序、篩選和匯出各自支援具名預設組態與獨立版本。持久化預設使用 localStorage，也可注入遠端介接器。內建 JSON/CSV 匯出。XLSX 使用獨立的選用介接器：
+
+```tsx
+import { exportXlsx } from '@zeroman.yang/react-auto-components/xlsx';
+// <AutoTable ... exportXlsx={exportXlsx} />
+```
+
+ExcelJS 會在首次使用介接器時動態載入，並排除於元件庫的主要進入點之外。只使用 CSV/JSON 的應用程式可在安裝時略過選用相依套件。
+
+## 驗證
+
+```sh
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm prepare:test-project
+pnpm --dir test-project build
+pnpm exec playwright install chromium  # 僅首次執行
+pnpm test:e2e
+```
+
+單元測試涵蓋欄位、非同步驗證、查詢、對話方塊、虛擬化、表格、設定遷移和匯出。Playwright 測試透過打包後的公開進入點測試互動。桌面／行動版螢幕截圖儲存至 `test-project/test-results`。
+
+## 行為與慣例
+
+- 這是專為 React 設計的 API，並非逐一對應 Vue 屬性或方法的相容層。請參閱[遷移指南](migration.md)。
+- 資料由應用程式碼管理。CRUD 回呼負責持久化變更；失敗時擲出例外即可保留編輯內容。成功後，元件會重新整理遠端資料。本機資料必須由呼叫端更新。
+- 表格的 `id` 必須在命名空間內唯一，`rowKey` 則必須在所有頁面和樹狀節點間唯一。伺服器端模式必須明確提供 `columns`，資料來源需回傳總筆數。
+- 當 `query` / `value` 為受控狀態時，父元件必須處理回呼並更新其值。非受控使用方式可省略這些 props。
+- 合併儲存格使用非虛擬化的語意化表格，適合分頁資料，可避免 rowSpan 在不同虛擬視窗間錯位。
+- 伺服器端針對所有篩選結果的彙總透過 `summaryValues` 提供。缺少彙總時顯示 `—`，不會將當頁合計當成整體合計。設定 `summaryScope="page"` 可明確計算當頁彙總。
+- 上傳進行中會暫停提交。重設、替換欄位值或卸載會取消舊的上傳；延遲回傳的結果無法覆寫較新的值。
+- 遠端匯出所有篩選結果時，會逐頁請求資料。大型應用程式可以自行實作伺服器端匯出。
+- 請明確從 `style.css` 匯入瀏覽器樣式。JavaScript 模組可在沒有 `window` 的 Node 環境中匯入。
+
+## 使用 AutoTable 填滿剩餘高度
+
+`height={440}` 仍會為資料捲動區設定固定高度。使用 `height="auto"` 時，整張表格會填滿父層版面配置分配的高度。搜尋區、工具列和分頁使用其自然高度；資料區使用剩餘空間並獨立捲動：
+
+```tsx
+<div style={{ height: '100dvh', display: 'flex', flexDirection: 'column', gap: 12 }}>
+  <header>頁面標題與描述</header>
+  <AutoTable<Person> id="people" rowKey="id" data={rows}
+    columns={columns} height="auto" />
+  <footer>頁面頁尾</footer>
+</div>
+```
+
+父層必須有確定的高度。在巢狀 flex 容器中使用 `flex: 1; min-height: 0` 將剩餘空間向下傳遞，或在 grid 版面中使用 `grid-template-rows: auto minmax(0, 1fr) auto`。不需要用 JavaScript 計算視窗高度減去工具列高度：版面配置會處理搜尋欄位的新增／移除、工具列換行及父層尺寸變更，虛擬清單則會跟隨捲動區的實際尺寸。
+
+這不會依資料列數量調整表格大小。空資料集或少量資料仍會填滿可用空間。父層至少必須容納搜尋區、工具列和分頁本身。
+
+測試專案在 **AutoTable → 剩餘高度** 分頁展示此功能，同時保留側邊欄和頁首。舊版網址 `http://127.0.0.1:4173/?demo=auto-height` 會直接選取該分頁。瀏覽器測試位於 `test-project/tests/auto-height.spec.ts`。
+
+## 全域表單版面配置
+
+使用 `AutoConfigProvider.config.form` 可統一設定一般表單、搜尋面板、表格搜尋區和對話方塊表單。標籤可放在控制項上方或左側，文字靠左／靠右對齊可獨立設定。預設為上方標籤與寬鬆間距。
+
+```tsx
+<AutoConfigProvider config={{
+  form: {
+    labelPosition: 'left', // 'top'：在上方；'left'：在控制項左側
+    labelAlign: 'right',   // 文字靠右對齊；標籤位於控制項左側
+    labelWidth: 80,
+    density: 'compact',   // 'comfortable'：間距較寬鬆
+  },
+}}>
+  <App />
+</AutoConfigProvider>
+```
+
+巢狀 Provider 會逐一合併版面設定屬性。明確指定的元件 props 優先於外層 Provider。例如，全域使用行內標籤時，仍可讓個別表單保留上方標籤：
+
+```tsx
+<AutoForm fields={fields} labelPosition="top" density="comfortable" />
+<AutoTable id="people" rowKey="id" data={rows} columns={columns}
+  searchFields={searchFields}
+  searchLayout={{ labelWidth: 100, columns: 3 }} />
+```
+
+`labelWidth` 預設為 `"auto"`，也接受像素數值或 `"6em"` 等 CSS 寬度。自動模式下，每個搜尋標籤依文字調整寬度；一般表單與對話方塊表單則依可見標籤共用寬度，讓控制項對齊。長標籤最多佔欄位寬度的 45%，超出部分會換行，保留控制項的空間。明確設定的固定寬度不受此自動上限限制。緊密的搜尋區在空間允許時會將操作按鈕放在同一列，窄螢幕則換行。標籤關聯保持完整，錯誤與說明會對齊控制項，長標籤可換行。
+
+在示範專案中，從側邊欄或右上角齒輪開啟 **全域設定**，即可修改版面、密度、標籤寬度和主題。變更會立即生效，且不會清除目前輸入。表單頁面支援 **跟隨全域** 或區域覆寫。示範專案透過 Provider 明確啟用緊密的行內版面。
+
+## 全域尺寸與密度
+
+`AutoConfigProvider` 支援 `size: "small" | "medium" | "large"` 和 `density: "compact" | "comfortable"`。明確指定的元件 props 優先於元件類別設定，而元件類別設定優先於全域值：
+
+```tsx
+<AutoConfigProvider config={{
+  size: "medium",
+  density: "compact",
+  form: { labelPosition: "left", labelAlign: "right" },
+  table: { density: "compact" },
+  tabs: { density: "compact" },
+}}>
+  <AutoForm fields={fields} size="small" />
+</AutoConfigProvider>
+```
+
+表格密度也支援 `normal`。表格設定面板預設跟隨全域設定。選擇緊密、一般或寬鬆間距會覆寫全域密度，並與版面預設組態一同儲存；元件的 `density` prop 具有最高優先權。巢狀元件的區域尺寸會各自獨立套用。
+
+表單支援 `resetLabel`、`extraActions` 和 `onReset`；搜尋面板支援 `searchLabel`、`resetLabel` 和 `extraActions`；對話方塊支援 `cancelLabel` 和 `extraActions`。`AutoTabs` 項目可定義 `badge`，`AutoTable.empty` 可自訂空白狀態內容。
+
+### AutoChat
+
+AutoChat 提供輕量的對話版面，具備串流跟隨、歷史載入與輸入區。供應 React 內容或 renderMessage 來渲染訊息，無需額外的執行時相依套件。
+
+[AutoChat API](auto-chat.md)