@taocompany/magic-grid 0.13.9 → 0.14.0

package/AGENTS.md

@@ -0,0 +1,47 @@
+# Magic Grid — Agent 约束
+
+面向消费 `@taocompany/magic-grid` 的代码生成（读 `node_modules` 即可，勿依赖本仓库 playground）。
+
+## 事实源优先级
+
+1. `dist/api-manifest.json`（与安装版本绑定）
+2. `dist/types/core.d.ts` + 组件 `MagicGrid.vue.d.ts`
+3. 本文件与 `llms.txt`
+
+## 命名（勿用其他表格库字段名）
+
+生成代码须使用本库 API，勿沿用常见误写字段：
+
+| 误写 | 本库 |
+|------|------|
+| columnDefs | columns |
+| rowData | data |
+| field (列) | prop |
+| headerName | label |
+| colId (列) | key |
+
+## 组件用法
+
+- 单文件组件：`<MagicGrid :columns="columns" :data="data" row-key="id" />`
+- 需要命令式 API：`import { MagicGrid, type MagicGridComponent } from '@taocompany/magic-grid'` + `import type { MagicGridExpose } from '@taocompany/magic-grid/types/core'` → `ref<InstanceType<MagicGridComponent> & MagicGridExpose>()` → `gridRef.value?.api`
+- `indexMode`（`'source' \| 'display'`）是 **GridApi.moveRow/moveRows 选项**，不是组件 prop。
+
+## 样式
+
+```ts
+import '@taocompany/magic-grid/tokens.css'
+import '@taocompany/magic-grid/style.css'
+```
+
+## 树形
+
+- `tree: true` 时必须提供 `getDataPath`（否则运行时报错）。
+- `tree` 与 `rowGrouping` 不能同时为 true。
+
+## 校验
+
+若项目配置了 `@taocompany/magic-grid-mcp`，优先调用 `validate_magic_grid_usage`；注意返回里的 `unchecked`，非字面量绑定不会全量验证。模板 `@event` 拼写错误由规则 **`unknown-emit`** 拦截（勿假设 `vue-tsc` 对全部 emit 名都能报错）。配置样例见仓库 `docs/ai/mcp-client-setup.md`（npm 包用户可读对应版本的 GitHub / 内网文档）。
+
+## 版本
+
+以 `package.json` 的 `@taocompany/magic-grid` 版本为准；manifest 内 `libraryVersion` 应一致。`@taocompany/magic-grid-mcp` **与库同 semver 发布**（升库版本后运行 `pnpm mcp:version:sync`）。

package/README.md

@@ -1,6 +1,6 @@
 # Magic Grid
 
-面向 Vue 3 的高性能虚拟表格组件库。采用命令式渲染 + 行 DOM 池 + 双轴虚拟化，可稳定承载百万级行数据；API 设计对标 [AG Grid](https://www.ag-grid.com/) 社区版，覆盖排序、筛选、编辑、行分组、树形表格、框选、剪贴板等完整表格能力。
+面向 Vue 3 的通用高性能虚拟表格组件库。采用命令式渲染 + 行 DOM 池 + 双轴虚拟化，可稳定承载百万级行数据；提供排序、筛选、编辑、行分组、树形表格、框选、剪贴板等完整表格能力。
 
 ## 目录
 
@@ -53,6 +53,7 @@
   - [ColumnSettingsPanel](#columnsettingspanel)
   - [ColumnSettingsMenuItem](#columnsettingsmenuitem)
   - [ColumnSettingsMenuIcon](#columnsettingsmenuicon)
+- [文档与 Agent 工具](#文档与-agent-工具)
 - [包入口与导出](#包入口与导出)
 - [TypeScript 集成](#typescript-集成)
 - [类型与校验子路径](#类型与校验子路径)
@@ -73,7 +74,7 @@
 | **体验** | 溢出 Tooltip、单元格批注、空态 Overlay、暗色主题、底部状态栏 |
 | **扩展** | 列设置面板、内置编辑器（text/number/checkbox/switch）、Vue 第三方编辑器 Composable、inline 常驻编辑器、async-validator 校验 |
 
-当前版本：**0.7.5**（`@taocompany/magic-grid`）。
+当前版本：**0.14.0**（`@taocompany/magic-grid`）。
 
 > **上手路径**：安装 → [快速开始](#快速开始) → 按需查阅 [行移动](#行移动)、[树形表格](#树形表格) 等专题，以及下文 Props / Events / GridApi 索引。
 
@@ -100,12 +101,29 @@ import '@taocompany/magic-grid/style.css'
 
 > **ColumnSettingsButton / ColumnSettingsPanel** 与 MagicGrid 共用上述两份 CSS。按钮若在 **MagicGrid 容器外**，同样必须引入；列设置相关 token 在 `.mg-column-settings-button` / `.mg-column-settings-portal` 上也会注入，脱离 `.magic-grid` 可正常显示。主题拆分见 [docs/48-theme-tokens-style-split.md](docs/48-theme-tokens-style-split.md)；平台自定义 token 与可视化导出方案见 [docs/49-theme-studio.md](docs/49-theme-studio.md)（在 `tokens.css` 之后加载 `mg-theme-overrides.css`）。
 
+---
+
+## 文档与 Agent 工具
+
+本文档面向**人类开发者**：用法、行为说明与 API 索引。随 npm 包发布的 **Agent 契约**（硬约束、校验规则、props/emits 机器摘要、recipe 代码）在独立文件中维护，**不在 README 重复**。
+
+| 资源 | 读者 | 说明 |
+|------|------|------|
+| 本文 README | 人 | 功能说明、示例、Props / Events / Slots |
+| [docs/](docs/) | 人 | 架构、阶段设计与专题（行移动、树形、Theme Studio 等） |
+| 包内 `AGENTS.md` | Agent | 短约束清单（npm `files`） |
+| 包内 `llms.txt` | Agent | 入口索引 |
+| 包内 `dist/api-manifest.json` | Agent / MCP | 与安装版本绑定的 API 摘要（`exports`: `@taocompany/magic-grid/api-manifest.json`） |
+| [`@taocompany/magic-grid-mcp`](packages/magic-grid-mcp/) | Agent / CI | 同版本号的 MCP 与 `mgc check` / `doctor`；配置见 [docs/ai/mcp-client-setup.md](docs/ai/mcp-client-setup.md) |
+| [docs/ai/ai-adoption-plan.md](docs/ai/ai-adoption-plan.md) | 维护者 | 语义层 / 工具层方案总览 |
+
+本地 Playground 文档站：`pnpm dev` 后访问开发服务器中的 `/docs` 路由（内网/开发环境；npm 消费者不依赖该站点）。
 
 ---
 
 ## 架构与设计
 
-Magic Grid 采用 **命令式渲染内核 + Vue 薄封装** 的分层架构，对标 AG Grid 社区版 API 语义，渲染路径针对百万级行数据做了专门优化。
+Magic Grid 采用 **命令式渲染内核 + Vue 薄封装** 的分层架构，对外以稳定的 Props / Events / `GridApi` 契约组织能力，渲染路径针对百万级行数据做了专门优化。
 
 ### 分层结构
 
@@ -440,7 +458,7 @@ api.moveRow(rowId, toIndex, 'display')
 
 ## 树形表格
 
-树形表格（Tree Table）在 **扁平 `data` 数组** 上，通过 **`getDataPath`** 为每行提供 **从根到当前节点的路径**（`string[]`），内核据此构建层级并 **DFS 投影** 为可见的 `rowsToDisplay`。对标 [AG Grid Tree Data](https://www.ag-grid.com/javascript-data-grid/tree-data/) 社区版语义。
+树形表格（Tree Table）在 **扁平 `data` 数组** 上，通过 **`getDataPath`** 为每行提供 **从根到当前节点的路径**（`string[]`），内核据此构建层级并 **DFS 投影** 为可见的 `rowsToDisplay`。
 
 > **与行分组互斥**：`tree: true` 与 `rowGrouping: true` **不得同时生效**。双开时控制台 dev 警告，**`tree` 优先**，`rowGrouping` 及 `ColumnDef.rowGroup` 被忽略。flat / group / tree 三选一，见 [概述与核心概念](#概述与核心概念)。
 
@@ -448,7 +466,7 @@ api.moveRow(rowId, toIndex, 'display')
 
 #### 为什么用扁平数组 + getDataPath？
 
-Magic Grid **不支持**嵌套 `children` 字段作为树数据源（与 AG Grid CSRM 一致）。所有行仍存放在 **同一个 `data` 数组** 中；层级关系完全由 **`getDataPath({ data }) => string[]`** 表达：
+Magic Grid **不支持**嵌套 `children` 字段作为树数据源。所有行仍存放在 **同一个 `data` 数组** 中；层级关系完全由 **`getDataPath({ data }) => string[]`** 表达：
 
 | 概念 | 说明 |
 |------|------|
@@ -565,7 +583,7 @@ const getDataPath: GetDataPathFn = ({ data }) =>
 | `getDataPath` | `GetDataPathFn` | — | `( { data } ) => string[]`，每行返回路径。**`tree: true` 时必填**，缺失则 throw |
 | `groupDefaultExpanded` | `number` | `-1` | 默认展开层级（tree / group **共用**此 prop）。`0` = 全折叠；`1` = 仅展开第一层；`-1` = 全部展开 |
 | `showTreeColumn` | `boolean` | `true` | 是否注入 tree 系统列（colId `__tree__`） |
-| `autoTreeColumnDef` | `Partial<ColumnDef>` | — | 覆盖 tree 列宽、pinned、headerName 等；对标 AG Grid `autoGroupColumnDef` |
+| `autoTreeColumnDef` | `Partial<ColumnDef>` | — | 覆盖 tree 列宽、固定、表头等；等价于对内置 tree 系统列的 `ColumnDef` 覆盖 |
 | `treeValueGetter` | `TreeValueGetterFn` | — | 自定义 tree 列展示文案；缺省为 **`dataPath` 末段** |
 | `treeDisplayType` | `'singleColumn'` | `'singleColumn'` | v1 仅单列树展示 |
 | `treeLazyLoad` | `boolean` | `false` | 启用 CSRM 懒加载；`true` 时需 `loadTreeChildren` |
@@ -668,7 +686,7 @@ api.applyTransaction({ remove: ['fe', 'be'] })
 
 #### getDataPath 与 getData() 的关系
 
-- `api.getData()` 返回 **flat sourceRows**（与 AG Grid 一致），**不是** DFS 投影顺序。
+- `api.getData()` 返回 **flat sourceRows**（业务数组顺序），**不是** DFS 投影顺序。
 - `api.getDataPath(rowId)` 查询某行的当前路径。
 - 展示顺序以 **`rowsToDisplay`** 为准；行索引列对 display 行 **连续编号**（1…N）。
 
@@ -1172,6 +1190,39 @@ async function persistMove(params: AsyncRowMutationMoveParams): Promise<void> {
 | `height` | `string \| number` | `'100%'` | 容器高度；number / 纯数字字符串 → `px`，亦支持 `%` / `vh` 等 |
 | `width` | `string \| number` | `'100%'` | 容器宽度；解析规则同 `height` |
 
+#### 行模型与加载更多
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rowModelType` | `'clientSide' \| 'infinite'` | `'clientSide'` | 行模型：默认全量 `data`；`infinite` 为块加载虚拟行 |
+| `infiniteDatasource` | `InfiniteRowDatasource` | — | **`rowModelType="infinite"` 时必填**。实现 `getRows`，通过 `successCallback(rows, lastRow)` 回传块数据 |
+| `blockSize` | `number` | `100` | infinite：每块行数 |
+| `maxBlocksInCache` | `number` | `10` | infinite：LRU 最多保留块数 |
+| `loadMoreRow` | `LoadMoreRowOptions` | — | **clientSide**：在 display 末尾展示「加载更多」行（`enabled` / `hasMore` / `loading` 等） |
+| `loadMoreRowRenderer` | `LoadMoreRowRendererFn` | — | 自定义 load-more 行（与 `#load-more-row` 插槽二选一） |
+
+infinite 最小示例（无需 `:data`，由 datasource 按块提供）：
+
+```vue
+<MagicGrid
+  :columns="columns"
+  row-key="id"
+  row-model-type="infinite"
+  :infinite-datasource="infiniteDatasource"
+/>
+```
+
+clientSide 末尾加载更多：
+
+```vue
+<MagicGrid
+  :columns="columns"
+  :data="data"
+  row-key="id"
+  :load-more-row="{ enabled: true, hasMore: true }"
+/>
+```
+
 #### 外观
 
 | Prop | 类型 | 默认值 | 说明 |
@@ -1475,7 +1526,7 @@ interface RowSelectionConfig {
 
 #### Grid 级默认与列级覆盖
 
-以下 Grid Prop 可一次性为**所有用户列**设定默认行为；列级字段显式配置时**以列为准**（对齐 AG Grid `defaultColDef` 语义）：
+以下 Grid Prop 可一次性为**所有用户列**设定默认行为；列级字段显式配置时**以列为准**（列级覆盖 Grid 默认）：
 
 | Grid Prop | 列级字段 | 默认值 | 说明 |
 |-----------|----------|--------|------|
@@ -3735,7 +3786,7 @@ api.clearValidation()
 
 ## 辅助组件
 
-表格列设置（Phase 27）提供一组**独立组件**，对标 AG Grid 的 Side Bar + Columns Tool Panel。只要持有 `GridApi` 即可使用，不强依赖 MagicGrid 内部 DOM。
+表格列设置（Phase 27）提供一组**独立组件**（列显隐、顺序、固定等），用于侧边栏或工具栏场景。只要持有 `GridApi` 即可使用，不强依赖 MagicGrid 内部 DOM。
 
 > **样式**：须全局引入 `tokens.css` 与 `style.css`（见 [引入样式](#引入样式)）。组件类名以 `mg-column-settings-*` 为前缀。
 
@@ -3797,7 +3848,7 @@ function onResetColumnOrder(api: GridApi) {
 </template>
 ```
 
-#### 方式 B：页头 / 外部工具栏（ERP 常见）
+#### 方式 B：页头 / 外部工具栏
 
 按钮放在 MagicGrid **外部**（如页面「新增」「刷新」旁）时，省略 `portalEl` 即可 Teleport 到 `document.body`；须确保已引入 `tokens.css` 与 `style.css`（见 [引入样式](#引入样式)）：
 
@@ -4060,6 +4111,8 @@ import type { ColumnSettingsMenuIconName } from '@taocompany/magic-grid/types/co
 | `@taocompany/magic-grid/validation` | 校验运行时（`enrichColumnsWithValidation`、`Schema` 等） |
 | `@taocompany/magic-grid/tokens.css` | 设计 token（`--mg-*`，**必须**先于 style 引入） |
 | `@taocompany/magic-grid/style.css` | 组件样式（**必须**手动引入） |
+| `@taocompany/magic-grid/token-catalog.json` | Theme Studio / token 可视化用目录（可选） |
+| `@taocompany/magic-grid/api-manifest.json` | 构建期 API 摘要 JSON（Agent / MCP；规则正文见 manifest，不在 README 复述） |
 
 ### 主入口运行时导出