@zeroman.yang/react-auto-components 0.1.0

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

@@ -0,0 +1,82 @@
+# AutoChat
+
+[English](../../auto-chat.md) | [简体中文](../zh-CN/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-TW/migration.md

@@ -0,0 +1,71 @@
+# 元件整合指南
+
+[English](../../migration.md) | [简体中文](../zh-CN/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 API | 可執行範例／測試 |
+| --- | --- | --- |
+| 表單欄位與 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)} /> },
+];
+```
+
+完整 API 請參閱匯出的 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>
+```
+
+本機變更會立即套用;遠端儲存會依序執行,失敗後可選擇重試。變更已持久化設定的格式時,請使用新的 table id 或版本,以避免載入不相容的設定。

package/docs/migration.md

@@ -0,0 +1,71 @@
+# Component integration guide
+
+**English** | [简体中文](i18n/zh-CN/migration.md) | [繁體中文](i18n/zh-TW/migration.md) | [日本語](i18n/ja/migration.md) | [한국어](i18n/ko/migration.md) | [Español](i18n/es/migration.md) | [Français](i18n/fr/migration.md) | [Deutsch](i18n/de/migration.md) | [Português (Brasil)](i18n/pt-BR/migration.md) | [Русский](i18n/ru/migration.md)
+
+Configure components through React generics, callbacks, and providers. The following table maps common application needs to the public APIs and runnable examples.
+
+| Original use case | React API | Runnable example / test |
+| --- | --- | --- |
+| Form fields and v-model | `fields: Field<T>[]`, `value/onChange`, or `defaultValue` | Form page in `test-project/src/examples/FormDemo.tsx`; `tests/form*.test.tsx` |
+| Slots and appended content | Field `render`, column `render/header`, ReactNode | Form/table pages |
+| Form instance operations | `ref.validate/reset/getValues/setValue/focus` | `tests/form.test.tsx` |
+| Search, related conditions, RSQL | `buildQuery`, `matchesQuery`, `serializeRsql` | Search page; `tests/query.test.ts` |
+| Local/remote table data | Either `data` or `dataSource(query,{signal})` | Table page; `tests/table.test.tsx` |
+| Layout/filter/sort/export presets | Independent presets in the settings dialog, invalidated separately by `versions` | Table page; `tests/table-settings.test.ts` |
+| Trees, details, summaries, merged cells | `getChildren/renderExpanded`, column `summary/merge` | Tree and expansion examples; `tests/table-advanced.test.tsx` |
+| Add, edit, delete | `formFields` and `onAdd/onEdit/onDelete` | Browser CRUD tests |
+| Imperative dialogs | `AutoDialogProvider` + `useAutoDialog().open()` | Dialog page; `tests/dialog.test.tsx` |
+| Tabs and nested tabs | `AutoTabs` items, value/onChange, keepMounted | Tabs page; `tests/tabs.test.tsx` |
+| Chat message lists and conversation UI | `AutoChat`, `messages`, `onSend`, `renderMessage` | Chat pages in `test-project/src/examples/Chat*.tsx`; `tests/chat.test.tsx` |
+
+## Field types
+
+`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` virtualizes options. Date ranges use two native inputs with separate labels; `dateValue` chooses strings or timestamps. Numeric inputs allow intermediate editing states; use field rules to validate business constraints on submission. `rules` supports async validation, while hidden fields skip validation. Options preserve numeric/boolean values instead of coercing them to strings.
+
+```tsx
+const fields: Field<User>[] = [
+  { name: 'name', label: 'Name', required: true },
+  { name: 'note', label: 'Note', hidden: values => !values.enabled,
+    render: ({ value, onChange, disabled }) =>
+      <textarea disabled={disabled} value={String(value ?? '')}
+        onChange={event => onChange(event.target.value)} /> },
+];
+```
+
+See the exported TypeScript types for the full API. `Field<T>` binds to actual keys of T; structural items such as titles and tips do not need a data property.
+
+## Server-side data sources
+
+```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('Failed to load');
+  return response.json(); // { rows: User[], total: number }
+};
+```
+
+Page indexes start at 0. `sort` is an ordered array of fields; `filter` is a structured query tree. Components cancel old requests and prevent late responses from overwriting newer queries. Call the table's `ref.refresh()` when business conditions outside the data-source closure change. Keep the data-source function stable to avoid unnecessary requests. RSQL serialization is only an adapter for backends that require it; it does not execute query strings.
+
+## Application uploads and persistence
+
+A field's `upload(files, signal)` returns the field value after the application saves the files. The component displays upload failures; callers provide upload URLs, authentication, and object-storage policies.
+
+```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>
+```
+
+Local changes apply immediately; remote saves run serially, with a retry option after failures. When changing persisted settings formats, use a new table id or version to avoid loading incompatible settings.

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@zeroman.yang/react-auto-components",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs/migration.md",
+    "docs/i18n/*/README.md",
+    "docs/i18n/*/migration.md",
+    "docs/auto-chat.md",
+    "docs/i18n/*/auto-chat.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./dist/style.css",
+    "./xlsx": {
+      "types": "./dist/adapters/xlsx.d.ts",
+      "import": "./dist/xlsx.js"
+    }
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "vite --config vite.demo.config.ts",
+    "build": "vite build && tsc -p tsconfig.build.json && node scripts/finalize-build.mjs",
+    "build:demo": "vite build --config vite.demo.config.ts",
+    "demo:build": "pnpm build && pnpm prepare:test-project && pnpm build:demo",
+    "demo:screenshot": "node scripts/update-demo-screenshot.mjs",
+    "demo:update": "node scripts/update-demo.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check:public": "node scripts/check-public-source.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",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm typecheck && pnpm test"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0 <20",
+    "react-dom": ">=19.0.0 <20"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "pnpm@12.5.1",
+  "dependencies": {
+    "@floating-ui/react": "^0.27.20",
+    "@radix-ui/react-context-menu": "^2.3.7",
+    "@radix-ui/react-dialog": "^1.1.23",
+    "@radix-ui/react-tabs": "^1.1.21",
+    "@tanstack/react-form": "^1.33.5",
+    "@tanstack/react-table": "^9.2.4",
+    "@tanstack/react-virtual": "^3.14.13"
+  },
+  "devDependencies": {
+    "@babel/core": "^8.0.6",
+    "@playwright/test": "^1.63.0",
+    "@rolldown/plugin-babel": "^0.2.4",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "jsdom": "^30.1.1",
+    "prettier": "^3.9.9",
+    "react": ">=19.0.0 <20",
+    "react-dom": ">=19.0.0 <20",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2"
+  },
+  "optionalDependencies": {
+    "exceljs": "^4.4.0"
+  },
+  "description": "Schema-driven React 19 components for forms, tables, search, dialogs, menus, tabs and chat.",
+  "license": "MIT",
+  "author": "Zeroman",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zeroman/react-auto-components.git"
+  },
+  "homepage": "https://github.com/Zeroman/react-auto-components#readme",
+  "bugs": {
+    "url": "https://github.com/Zeroman/react-auto-components/issues"
+  },
+  "keywords": [
+    "react",
+    "typescript",
+    "components",
+    "form",
+    "table",
+    "schema-driven",
+    "virtualization",
+    "chat"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}