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

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

@@ -0,0 +1,62 @@
+# AutoForm
+
+[English](../../auto-form.md) | [简体中文](../zh-CN/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-TW/auto-menu.md

@@ -0,0 +1,47 @@
+# AutoMenu
+
+[English](../../auto-menu.md) | [简体中文](../zh-CN/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-TW/auto-search.md

@@ -0,0 +1,55 @@
+# AutoSearch
+
+[English](../../auto-search.md) | [简体中文](../zh-CN/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-TW/auto-table.md

@@ -0,0 +1,62 @@
+# AutoTable
+
+[English](../../auto-table.md) | [简体中文](../zh-CN/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-TW/auto-tabs.md

@@ -0,0 +1,44 @@
+# AutoTabs
+
+[English](../../auto-tabs.md) | [简体中文](../zh-CN/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` | 標籤仍可見，但不能選。預設選中會跳過停用標籤。 |
+
+某一項如果有 `children`，就用巢狀標籤代替 `content`。`defaultActive` 是巢狀層的非受控 id。
+
+## 前置條件
+
+入口引入一次 `style.css`（開發模式 `RAC-CSS-MISSING`）。`AutoConfigProvider` 可選。
+
+## 動態標籤
+
+`useAutoTabsWorkspace` 在沒有路由器時維護一組頁面。把 `tabsProps` 傳給 `AutoTabs`。同一個 id 再次 `open` 只會切到該標籤並保留草稿。固定標籤不能關閉。等到 `ready` 再呼叫 `open`。選中項、`params` 和 `state` 會在掛載後從 `sessionStorage` 恢復。`beforeClose` 回傳 `false` 或拋錯都會取消關閉。示範見 [AutoTabs 頁](../../../test-project/src/examples/DynamicTabsDemo.tsx)。

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

@@ -0,0 +1,112 @@
+# 錯誤碼
+
+[English](../../errors.md) | [简体中文](../zh-CN/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/llms.txt

@@ -0,0 +1,69 @@
+# @zeroman.yang/react-auto-components
+
+Schema-driven React 19 components. Read this file first. Behavior, thrown callbacks, and error codes live in the docs below. The README is for people running the demo.
+
+## Docs
+
+- Forms and fields: docs/auto-form.md
+- Search (`AutoSearch`) and the query AST: docs/auto-search.md
+- Tables: docs/auto-table.md
+- Dialogs: docs/auto-dialog.md
+- Tabs, including dynamic tabs: docs/auto-tabs.md
+- Menu: docs/auto-menu.md
+- Chat: docs/auto-chat.md
+- Error codes: docs/errors.md
+
+Each component doc has a "Behavior and props" table. That table is the callback contract, including what happens when a callback throws. English docs are the source. `docs/i18n/*` mirrors them.
+
+## Contracts
+
+- `Field<T>` is a discriminated union. `select` without `options`, a scalar on `daterange` / `datetimerange`, and `match: "between"` on a scalar are TypeScript errors. `AnyField` and `unsafeField()` skip the checks. Development mode still warns.
+- `QueryNode` is a JSON AST: `{ kind: "group", operator, children }` or `{ kind: "condition", field, operator, value }`.
+- Built-in UI strings are English. The same string is the `config.t` key and the fallback.
+- Developer failures throw `RacError`: component, problem, Fix, `Code RAC-…`, and a docs/errors.md anchor. The console message is English. UI copy stays on `userKey`.
+
+## JSON registries
+
+Register functions once on `AutoConfigProvider`. A description can then name them with a string.
+
+Canonical zero-function-props example (provider registration + pure JSON + source request/response contract): [JSON-driven table](docs/auto-table.md#json-driven-table-zero-function-props).
+
+- `Field.component` looks up `config.fields[key]`. `render` wins when both are set. Unknown custom fields warn `RAC-FIELD-CUSTOM`.
+- `AutoColumn.component` looks up `config.columns[key]` for `render`, `format`, `sort`, and `exportFormat`. A function on the column wins. An unknown key warns `RAC-COLUMN-COMPONENT` and the cell uses the default format.
+- `RowAction.action` looks up `config.rowActions[key]` when `onClick` is omitted. `onClick` wins. Neither one warns `RAC-ROW-ACTION` when the item is chosen, and the status shows the message.
+- `AutoTable source` looks up `config.sources[key]`. Pass exactly one of `data`, `dataSource`, or `source`. An unknown key warns `RAC-TABLE-SOURCE` and the table shows that message with retry.
+
+`config.fields`, `config.columns`, `config.rowActions`, and `config.sources` merge from nested providers. Later keys win.
+
+## Playwright
+
+`data-testid` does not follow `config.t` or the visible label. Scope button ids to `rac-table-{id}` or `rac-dialog` when more than one is on the page.
+
+- `rac-field-{name}` is the field wrapper. The control is inside it. The same node has `data-field="{name}"`.
+- `rac-table-{id}` is the table root.
+- Inside a table: `rac-add`, `rac-delete-selected`, `rac-refresh`, `rac-settings`, `rac-export`, `rac-retry`, `rac-edit-{rowId}`, `rac-delete-{rowId}`, `rac-expand-{rowId}`.
+- `rac-search-panel`, `rac-search`, `rac-search-reset`, `rac-more-filters`.
+- `rac-submit` and `rac-reset` are the form actions. Dialog forms hide those and use `rac-ok` and `rac-cancel`.
+- `rac-dialog`, `rac-dialog-close`, `rac-dialog-reset`.
+
+## Deterministic testing
+
+For AI self-verification, snapshots, or independent renders, disable persisted table layouts and dialog drafts with a no-op adapter:
+
+```tsx
+const storage = { get: () => undefined, set: () => {}, remove: () => {} };
+const config = { storage, settings: undefined };
+<AutoConfigProvider config={config}><App /></AutoConfigProvider>
+```
+
+Place this provider around the components under test; an inner app provider must not override it. `settings: undefined` also disables an inherited remote table-settings adapter. This isolates persistence only: use fixed data and mock network responses separately when needed.
+
+To test draft restoration or saved layouts within one test, inject memory storage instead. Create a fresh map per test and keep the same adapter across that test's rerenders:
+
+```tsx
+const values = new Map<string, unknown>();
+const storage = { get: (key: string) => values.get(key), set: (key: string, value: unknown) => { values.set(key, structuredClone(value)); }, remove: (key: string) => { values.delete(key); } };
+<AutoConfigProvider config={{ storage, settings: undefined }}><App /></AutoConfigProvider>
+```
+
+A browser reload discards this map. Tests that intentionally verify persistence across reloads should keep the default storage and use a fresh browser context per test. `useAutoTabsWorkspace` has separate storage; set its `storage: false` for isolated workspace tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroman.yang/react-auto-components",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "files": [
     "dist",
@@ -10,7 +10,22 @@
     "docs/i18n/*/README.md",
     "docs/i18n/*/migration.md",
     "docs/auto-chat.md",
-    "docs/i18n/*/auto-chat.md"
+    "docs/auto-form.md",
+    "docs/auto-search.md",
+    "docs/auto-table.md",
+    "docs/auto-dialog.md",
+    "docs/auto-tabs.md",
+    "docs/auto-menu.md",
+    "docs/errors.md",
+    "llms.txt",
+    "docs/i18n/*/auto-chat.md",
+    "docs/i18n/*/auto-form.md",
+    "docs/i18n/*/auto-search.md",
+    "docs/i18n/*/auto-table.md",
+    "docs/i18n/*/auto-dialog.md",
+    "docs/i18n/*/auto-tabs.md",
+    "docs/i18n/*/auto-menu.md",
+    "docs/i18n/*/errors.md"
   ],
   "exports": {
     ".": {
@@ -36,6 +51,7 @@
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "check:public": "node scripts/check-public-source.mjs",
+    "check:docs": "node scripts/check-docs-i18n.mjs",
     "test:e2e": "pnpm --dir test-project test",
     "prepare:test-project": "node scripts/prepare-test-project.mjs",
     "format": "prettier --write src tests test-project/src test-project/tests *.ts",

package/dist/components/AutoSearchPanel/index.d.ts

@@ -1,21 +0,0 @@
-import { type QueryNode } from "../../core/query";
-import type { Field, AutoFormLayout } from "../../core/types";
-export interface AutoSearchPanelProps<T extends object> extends AutoFormLayout {
-    fields: readonly Field<T>[];
-    value?: T;
-    defaultValue?: Partial<T>;
-    onChange?: (values: T) => void;
-    onSearch: (query: QueryNode, values: T) => void;
-    mode?: "manual" | "instant";
-    columns?: number;
-    disabled?: boolean;
-    searchLabel?: string;
-    resetLabel?: string;
-    extraActions?: React.ReactNode;
-    sortTags?: readonly {
-        id: string;
-        label: string;
-        onRemove: () => void;
-    }[];
-}
-export declare function AutoSearchPanel<T extends object>({ fields, value, defaultValue, onChange, onSearch, mode, columns, labelPosition, labelAlign, labelWidth, density: ownDensity, size: ownSize, disabled, searchLabel, resetLabel, extraActions, sortTags, }: AutoSearchPanelProps<T>): import("react").JSX.Element;