@taocompany/magic-grid 0.2.0 → 0.3.1

package/README.md

@@ -5,7 +5,9 @@
 ## 目录
 
 - [概述](#概述)
+- [架构与设计](#架构与设计)
 - [快速开始](#快速开始)
+- [数据与性能最佳实践](#数据与性能最佳实践)
 - [默认配置](#默认配置)
 - [Props](#props)
   - [MagicGrid Props](#magicgrid-props)
@@ -13,15 +15,22 @@
   - [ColumnDef 列定义](#columndef-列定义)
     - [列有效性与显隐](#列有效性与显隐)
 - [Options 类型参考](#options-类型参考)
+- [筛选模型参考](#筛选模型参考)
 - [Events](#events)
 - [Expose](#expose)
 - [Slots](#slots)
+- [单元格编辑](#单元格编辑)
+- [数据校验](#数据校验)
+- [键盘导航与快捷键](#键盘导航与快捷键)
 - [辅助组件](#辅助组件)
   - [ColumnSettingsButton](#columnsettingsbutton)
   - [ColumnSettingsPanel](#columnsettingspanel)
   - [ColumnSettingsMenuItem](#columnsettingsmenuitem)
   - [ColumnSettingsMenuIcon](#columnsettingsmenuicon)
-- [校验子路径](#校验子路径)
+- [包入口与导出](#包入口与导出)
+- [TypeScript 集成](#typescript-集成)
+- [类型与校验子路径](#类型与校验子路径)
+- [本地开发与 Playground](#本地开发与-playground)
 
 ---
 
@@ -37,6 +46,9 @@
 | **布局** | 固定列、列拖拽/调整宽度、列有效性与显隐（`available` / `hidden`）、合并单元格、动态行高、主从展开行 |
 | **结构** | 行分组、树形表格（含懒加载）、表尾汇总 |
 | **体验** | 溢出 Tooltip、单元格批注、空态 Overlay、暗色主题、底部状态栏 |
+| **扩展** | 列设置面板、Vue 第三方编辑器 Composable、inline 常驻编辑器、async-validator 校验 |
+
+当前版本：**0.3.0**（`@taocompany/magic-grid`）。
 
 ### 环境要求
 
@@ -60,6 +72,40 @@ import '@taocompany/magic-grid/style.css'
 
 > **ColumnSettingsButton / ColumnSettingsPanel** 与 MagicGrid 共用同一份 `style.css`。按钮或下拉菜单若放在页头工具栏等 **MagicGrid 容器外**，同样必须引入该文件；样式 token 已在 `.mg-column-settings-button` / `.mg-column-settings-portal` 上自带 fallback，脱离 `.magic-grid` 也可正常显示。
 
+
+---
+
+## 架构与设计
+
+Magic Grid 采用 **命令式渲染内核 + Vue 薄封装** 的分层架构，对标 AG Grid 社区版 API 语义，渲染路径针对百万级行数据做了专门优化。
+
+### 分层结构
+
+| 层级 | 职责 | 关键模块 |
+|------|------|----------|
+| **Vue 层** | Props / Events / Slots 绑定、主题 CSS 变量、辅助 UI | `MagicGrid.vue`、ColumnSettings、StatusBar |
+| **Grid API** | 命令式数据、列、编辑、选择、框选 | `GridApi` |
+| **渲染引擎** | 双轴虚拟化、行 DOM 池、增量 cell 刷新 | `rowRenderer`、`rowPool` |
+| **数据管线** | 排序 / 筛选 / 分组 / 树形 / 映射 | pipeline stages |
+| **交互层** | 焦点、框选、编辑、拖拽、剪贴板、批注 | `gridInteraction` |
+
+### 渲染模型
+
+- **行虚拟化**：仅渲染视口 + `rowBuffer` 缓冲行；行 DOM 在行池内按 `rowKey` 复用，滚动时更新内容与位置。
+- **列布局**：左固定 / 中心 / 右固定三 lane；中心 lane 随横滚分配列宽。
+- **增量更新**：`applyTransaction`、`setData` 走 RowNode 增量管线；`beginUpdate` / `endUpdate` 可合并多次刷新。
+- **帧预算**：大批量 DOM 写入分片到 `requestAnimationFrame`；测试场景可调用 `flushFrames()` 同步 flush。
+
+### 数据管线顺序
+
+| 模式 | Stage 顺序 |
+|------|------------|
+| 扁平表格 | `sort` → `filter` → `map` |
+| 行分组 | `group` → `filter` → `sort` → `aggregate` → `map` |
+| 树形表格 | `tree` → `filter` → `sort` → `map` |
+
+`summaryScope: 'displayed'`、状态栏行数、框选聚合均基于 `rowsToDisplay`；`summaryScope: 'all'` 对 `sourceRows` 全量汇总（忽略 filter）。
+
 ---
 
 ## 快速开始
@@ -68,7 +114,7 @@ import '@taocompany/magic-grid/style.css'
 <script setup lang="ts">
 import { ref } from 'vue'
 import { MagicGrid } from '@taocompany/magic-grid'
-import type { ColumnDef, MagicGridExpose, RowData } from '@taocompany/magic-grid'
+import type { ColumnDef, MagicGridExpose, RowData } from '@taocompany/magic-grid/types/core'
 import '@taocompany/magic-grid/style.css'
 
 const gridRef = ref<MagicGridExpose>()
@@ -123,6 +169,29 @@ const columns: ColumnDef[] = [
 <MagicGrid :columns="columns" :data="data" row-key="id" height="400" />
 ```
 
+
+---
+
+## 数据与性能最佳实践
+
+### 行数据
+
+- **`data` 使用普通对象数组**，不要对行数据做 `reactive()` 深代理；Grid 内部维护 RowNode，深代理会显著拖慢增量更新。
+- **`rowKey` 必须稳定唯一**（业务主键）；临时新增行可省略主键，内核分配 `__mg_tmp_*`，落库后调用 `promoteRowId`。
+- **大批量写入**优先 `applyTransaction` 或 `beginUpdate` / `endUpdate` 包裹多次 API 调用，避免连续 `setData` 全量替换。
+
+### 列定义
+
+- 动态列用 `columns` prop 热更新即可；`available: false` 从模型裁剪，`hidden: true` 保留模型仅不渲染。
+- flex 列与固定 `width` 列混用时，剩余空间由 flex 权重分配；`sizeColumnsToFit` / `autoSizeStrategy` 可首屏自适应。
+- 需要权限裁剪时用 `available`，需要用户临时隐藏列时用 `hidden` + 列设置面板。
+
+### 性能提示
+
+- 避免在 `cellRenderer` / `formatter` / `valueGetter` 中创建重量级对象或触发外部副作用；这些函数在滚动时会高频调用。
+- 合并单元格（`enableCellSpan`）会启用 `style.top` 行定位并增加 span cache 开销，仅在确有需求时开启。
+- Playground 内置 `getMetrics()` 可观察 `activeDomRowCount`、`lastSetDataMs` 等指标；生产环境可通过 `scroll` / `data-rendered` 事件订阅。
+
 ---
 
 ## 默认配置
@@ -227,7 +296,7 @@ const columns: ColumnDef[] = [
 
 | 配置项 | 默认值 | 说明 |
 |--------|--------|------|
-| `editMode` | `'cell'` | 单格编辑 |
+| `editBehavior` | `'cell'` | 单格编辑 |
 | `editType` | `'singleClick'` | 单击进入编辑 |
 | `invalidEditValueMode` | `'block'` | 校验失败保持编辑态 |
 
@@ -402,7 +471,7 @@ const columns: ColumnDef[] = [
 | `index` | `(rowIndex) => number \| string` | — | 自定义序号展示 |
 | `showRowDragHandle` | `boolean` | `false` | 在索引列显示行拖拽把柄 |
 | `enableRowResizer` | `boolean` | `false` | 索引列底边可拖拽调整行高 |
-| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | `'center'` | 对齐配置 |
 
 #### 行选择
 
@@ -430,7 +499,7 @@ interface RowSelectionConfig {
 | `width` | `number` | `40` | 列宽 px（最小 40） |
 | `selectAllLabel` | `string` | `'全选'` | 表头全选 checkbox 的 aria-label |
 | `rowLabel` | `(rowIndex) => string` | — | 行 checkbox 的 aria-label 工厂 |
-| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | `'center'` | 对齐配置 |
 
 #### 表尾汇总
 
@@ -477,7 +546,7 @@ interface RowSelectionConfig {
 
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `editMode` | `'cell' \| 'row'` | `'cell'` | 编辑范围：单格 / 整行 |
+| `editBehavior` | `CellEditBehavior` | `'cell'` | 编辑范围：单格 / 整行 |
 | `editType` | `CellEditType` | `'singleClick'` | 进入编辑态的触发方式 |
 | `invalidEditValueMode` | `'block' \| 'revert' \| 'keep'` | `'block'` | 校验失败后：`block` 保持编辑；`revert` 退出并恢复旧值；`keep` 退出编辑但保留无效值 |
 | `rowValidator` | `RowValidator` | — | 行编辑跨字段校验 |
@@ -810,9 +879,9 @@ Playground 验收：开发环境 `/phase22` · **T14–T15**（`legacyToken` 列
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `headerAlign` / `headerValign` | 对齐枚举 | 表头对齐；默认 `center` |
-| `align` / `valign` | 对齐枚举 | 表体对齐；默认 `center` |
-| `footerAlign` / `footerValign` | 对齐枚举 | 表尾对齐；默认 `center` |
+| `headerAlign` / `headerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | 表头对齐；默认 `center` |
+| `align` / `valign` | `GridHorizontalAlign` / `GridVerticalAlign` | 表体对齐；默认 `center` |
+| `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | 表尾对齐；默认 `center` |
 
 #### 禁用与样式
 
@@ -855,7 +924,7 @@ Playground 验收：开发环境 `/phase22` · **T14–T15**（`legacyToken` 列
 | `index` | `(rowIndex) => number \| string` | — | 自定义序号展示 |
 | `showRowDragHandle` | `boolean` | `false` | 在索引列显示行拖拽把柄 |
 | `enableRowResizer` | `boolean` | `false` | 索引列底边可拖拽调整行高 |
-| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | `'center'` | 对齐配置 |
 
 ### SelectionColumnOptions
 
@@ -866,7 +935,7 @@ Playground 验收：开发环境 `/phase22` · **T14–T15**（`legacyToken` 列
 | `width` | `number` | `40` | 列宽 px（最小 40） |
 | `selectAllLabel` | `string` | `'全选'` | 表头全选 checkbox 的 aria-label |
 | `rowLabel` | `(rowIndex) => string` | — | 行 checkbox 的 aria-label 工厂 |
-| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | `'center'` | 对齐配置 |
 
 ### RowSelectionConfig
 
@@ -1143,6 +1212,82 @@ type StatusBarRangeAggregationPrecisionInput =
 
 **ProcessDataFromClipboardParams**：`{ data: string[][], anchor: CellPosition }`，其中 `anchor` 为 `{ rowIndex, colId }`。
 
+
+---
+
+## 筛选模型参考
+
+筛选状态由 `FilterModel` 表示：`Record<colId, FilterCondition>`。通过 `setFilterModel` / `getFilterModel` / `filter-changed` 事件读写。
+
+### ColumnFilter（内置 UI / API 通用）
+
+单列条件结构（`filterType` 决定可用算子）：
+
+```ts
+interface ColumnFilter {
+  type: FilterType          // 算子，见下表
+  filter?: string           // 主比较值（文本 / 数字 / ISO 日期字符串）
+  filterTo?: string         // date inRange 第二端点
+  operator?: 'AND' | 'OR'   // 多条件组合，默认 AND
+  conditions?: ColumnFilterOperatorCondition[]  // 多条件列表，存在时优先于顶层 type/filter
+  setValues?: string[]      // 值选择：选中 key；缺省 = 全选（不约束）
+}
+```
+
+**文本列**（`filterType: 'text'`，默认）算子：
+
+| type | 说明 |
+|------|------|
+| `contains` / `notContains` | 包含 / 不包含 |
+| `equals` / `notEqual` | 等于 / 不等于 |
+| `startsWith` / `endsWith` | 前缀 / 后缀 |
+| `blank` / `notBlank` | 空 / 非空 |
+
+**数字列**（`filterType: 'number'`）额外支持：`lessThan`、`lessThanOrEqual`、`greaterThan`、`greaterThanOrEqual`。
+
+**日期列**（`filterType: 'date'`）v1 使用 ISO 文本（如 `2026-08-07`）；支持 `inRange`（需 `filter` + `filterTo`）。
+
+**值选择（set filter）**：表头 filter 面板勾选 distinct 值时写入 `setValues`；`filterSetValueMode: 'current'`（默认）在搜索时投影当前可见勾选，`'reserve'` 保留历史勾选。
+
+**Quick Filter**：Grid 级 `quickFilterText` 对全部 `filterable` 用户列做 OR 式 `contains`（不走 ColumnFilter 结构）。
+
+### CustomColumnFilter（编程式）
+
+```ts
+interface CustomColumnFilter {
+  predicate: (value: unknown, row: RowData) => boolean
+}
+```
+
+通过 `setColumnFilter(colId, { predicate: ... })` 设置；`getColumnFilter` 可读回。与内置 UI 筛选可并存（同一 colId 以后写入者为准）。
+
+### 示例
+
+```ts
+// 单列文本 contains
+api.setColumnFilter('name', { type: 'contains', filter: '张' })
+
+// 数字 greaterThanOrEqual
+api.setColumnFilter('amount', { type: 'greaterThanOrEqual', filter: '1000' })
+
+// 多条件 AND
+api.setColumnFilter('status', {
+  operator: 'AND',
+  conditions: [
+    { type: 'notEqual', filter: 'draft' },
+    { type: 'notEqual', filter: 'archived' },
+  ],
+})
+
+// 清除单列
+api.setColumnFilter('name', null)
+
+// 清除全部（含 quick filter）
+api.clearAllFilters()
+```
+
+---
+
 ---
 
 ## Events
@@ -1577,7 +1722,7 @@ interface MagicGridExpose {
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
-import type { MagicGridExpose } from '@taocompany/magic-grid'
+import type { MagicGridExpose } from '@taocompany/magic-grid/types/core'
 
 const gridRef = ref<MagicGridExpose>()
 
@@ -1797,7 +1942,7 @@ MagicGrid 提供**静态插槽**（固定名称）与**动态列插槽**（`#cel
 | 插槽 prop | 类型 | 说明 |
 |-----------|------|------|
 | `api` | `GridApi \| undefined` | GridApi 实例 |
-| `size` | `MagicGridSize` | 当前尺寸 preset |
+| `size` | `GridSize` | 当前尺寸 preset |
 | `portalEl` | `HTMLElement \| undefined` | 浮层挂载 portal 元素 |
 
 ```vue
@@ -1956,6 +2101,228 @@ MagicGrid 提供**静态插槽**（固定名称）与**动态列插槽**（`#cel
 
 ---
 
+
+## 单元格编辑
+
+Magic Grid 支持 **overlay**（点击/Enter 进入编辑浮层）与 **inline**（控件常驻单元格内）两种呈现模式，以及内置编辑器、函数编辑器、Vue 组件编辑器与命名注册表。
+
+### 呈现模式：overlay 与 inline
+
+| 模式 | 配置 | 行为 |
+|------|------|------|
+| **overlay**（默认） | `cellEditorMode: 'overlay'` 或省略 | 非编辑态展示 formatter / cellRenderer；进入编辑态后在单元格上方挂载编辑器 |
+| **inline** | `cellEditorMode: 'inline'` + 必须配置 `cellEditor` | 编辑器始终渲染在格内；空格切换 checkbox；适合布尔列、简单输入 |
+
+**inline 限制**（开发模式会 console.warn）：
+
+- 系统列（索引 / 行选择）不支持 inline。
+- 推荐搭配内置 `'text'` / `'number'` / `'checkbox'`；依赖 teleport/下拉的第三方组件（如 Select）应使用 overlay + `useCellEditor({ strategy: 'overlay' })`。
+- inline 列通过 `params.commit()` / 空格（checkbox）提交；不走 overlay 的 Enter 捕获逻辑。
+
+```ts
+const columns: ColumnDef[] = [
+  { prop: 'done', label: '完成', width: 80, cellEditorMode: 'inline', cellEditor: 'checkbox' },
+  { prop: 'qty', label: '数量', cellEditorMode: 'inline', cellEditor: 'number', editable: true },
+]
+```
+
+Grid 级 `editBehavior: 'row'` 时整行同时进入编辑；Tab 在同行可编辑列间循环。`editType: 'doubleClick'` 改为双击进入编辑。
+
+### 内置编辑器
+
+| 名称 | 说明 |
+|------|------|
+| `'text'` | 单行文本 input |
+| `'number'` | `type="number"` input |
+| `'checkbox'` | 布尔 checkbox；inline 模式下空格切换 |
+
+列定义引用：`cellEditor: 'text'`。内置名不可用于 `registerCellEditor` 覆盖。
+
+### Vue 自定义编辑器
+
+包导出以下工具，用于集成 Element Plus 等 Vue 组件：
+
+| 导出 | 用途 |
+|------|------|
+| `useCellEditor` | Composable：注册 `setGetValue`、键盘 Enter/Esc、change 提交策略 |
+| `createVueCellEditor` | 将 Vue 组件包装为 `CellEditorFn` |
+| `createSlotCellEditor` | 将 `#cell-editor-{colId}` 插槽包装为 `CellEditorFn`（MagicGrid 内部使用） |
+| `VueCellEditorHost` | Vue 编辑器挂载宿主 |
+
+**`useCellEditor` 策略**：
+
+| strategy | Enter | change 时提交 | 典型场景 |
+|----------|-------|---------------|----------|
+| `'input'`（默认） | 立即提交 | 否 | ElInput、原生 input |
+| `'overlay'` | 延迟（由组件确认） | 是 | ElSelect、DatePicker |
+
+```vue
+<!-- MyInputEditor.vue -->
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { CellEditorParams } from '@taocompany/magic-grid/types/core'
+import { useCellEditor } from '@taocompany/magic-grid'
+
+const props = defineProps<{ params: CellEditorParams }>()
+const draft = ref(props.params.formattedValue)
+
+useCellEditor(props.params, {
+  strategy: 'input',
+  getValue: () => draft.value,
+})
+</script>
+
+<template>
+  <input v-model="draft" class="my-cell-editor" />
+</template>
+```
+
+```ts
+import { createVueCellEditor } from '@taocompany/magic-grid'
+import MyInputEditor from './MyInputEditor.vue'
+
+const columns: ColumnDef[] = [
+  {
+    prop: 'note',
+    label: '备注',
+    editable: true,
+    cellEditor: createVueCellEditor(MyInputEditor),
+  },
+]
+```
+
+`CellEditorParams` 主要字段：`value`、`data`、`stopEditing(commit?)`、`validate()`、`cancelCommit()`、`setGetValue`、`setKeyboardPolicy`、`inline`、`commit`（inline 模式）。
+
+### 命名编辑器注册表
+
+除列级函数 / 内置名外，可通过 **命名引用** 复用编辑器：
+
+```ts
+import { registerCellEditor } from '@taocompany/magic-grid'
+
+registerCellEditor('statusSelect', createVueCellEditor(StatusSelectEditor))
+
+// 列定义
+{ prop: 'status', cellEditor: 'statusSelect', editable: true }
+
+// 或实例级（仅当前 Grid）
+<MagicGrid :cell-editor-registry="{ statusSelect: myEditorFn }" ... />
+```
+
+优先级：**列级函数** > **实例 `cellEditorRegistry`** > **全局 `registerCellEditor`** > **内置名**。
+
+异步提交：`valueSetter` 返回 Promise 时进入 `committing` 阶段；Esc 可 `cancelCommit()`。配合 `asyncRowMutation` 做服务端持久化。
+
+---
+
+
+## 数据校验
+
+校验可在 **编辑提交时**（inline / overlay 共用）与 **编程式 API**（`validate` / `validateRows` / `validateCells`）两个入口触发。
+
+### 列级规则
+
+| 方式 | 字段 | 优先级 |
+|------|------|--------|
+| 手写 | `cellValidator` | 最高 |
+| async-validator | `validationRules` | 次之 |
+| 必填标记 | `validationRequired` | 与 rules.required 联动 |
+
+`validationRules` 使用 [async-validator](https://github.com/yiminghe/async-validator) 语法；magic-grid 会将异步 `validator` 自动映射为 `asyncValidator`。
+
+### enrichColumnsWithValidation
+
+在传入 Grid 前编译 rules 为运行时 `cellValidator`（可选，也可直接写 `cellValidator`）：
+
+```ts
+import { enrichColumnsWithValidation } from '@taocompany/magic-grid/validation'
+
+const rawColumns: ColumnDef[] = [
+  {
+    prop: 'email',
+    label: '邮箱',
+    validationRules: [
+      { required: true, message: '必填' },
+      { type: 'email', message: '格式不正确' },
+    ],
+  },
+]
+
+const columns = enrichColumnsWithValidation(rawColumns)
+```
+
+### 行级校验
+
+`rowValidator` 在 **行编辑模式** 提交时运行，返回 `string[]` 错误或 `{ errors, failedColIds }` 结构。失败触发 `row-validation-failed`。
+
+### 失败后行为
+
+由 `invalidEditValueMode` 控制：
+
+| 值 | 行为 |
+|----|------|
+| `'block'`（默认） | 保持编辑态，展示错误 |
+| `'revert'` | 退出编辑并恢复旧值 |
+| `'keep'` | 退出编辑但保留无效值 |
+
+### 编程式校验 API
+
+```ts
+const result = await api.validate({ rowIds: [1, 2], showFeedback: true })
+// result.valid · result.cellErrors · result.rowErrors
+
+await api.validateCells({ cells: [{ rowId: 1, colId: 'email' }] })
+api.clearValidation()
+```
+
+---
+
+
+## 键盘导航与快捷键
+
+焦点在表格视口内时（非编辑态），内核处理以下按键。编辑态下 Enter / Esc 等由编辑器或 `useCellEditor` 优先处理。
+
+### 导航
+
+| 按键 | 行为 |
+|------|------|
+| `↑` `↓` `←` `→` | 移动单元格焦点 |
+| `Shift` + 方向键 | 扩展框选 range（`cellSelection` 开启时） |
+| `Ctrl/Cmd` + 方向键 | 跳转到首/末行或导航序首/末列 |
+| `Tab` / `Shift+Tab` | 下一 / 上一可聚焦格（表头 ↔ 表体可衔接，`navigateHeader` / `navigateFooter` 控制） |
+| `Enter` | 表头：排序 / 全选；索引列：定位；树/分组：展开折叠；数据格：进入编辑 |
+| `Space` | 行选择 checkbox；inline checkbox 切换；表头/索引/树/分组同 Enter 的切换逻辑 |
+| `F2` | 进入编辑（若列可编辑） |
+| `Shift+F2` | 新建/打开单元格批注（批注功能启用时） |
+
+### 框选与剪贴板
+
+| 按键 | 行为 |
+|------|------|
+| `Delete` / `Backspace` | 清空选区内可编辑格（触发 `cell-selection-delete-*` 事件） |
+| `Ctrl/Cmd+C` | 复制选区为 TSV（需 `enableCellCopy`） |
+| `Ctrl/Cmd+V` | 从剪贴板粘贴至选区锚点（需 `enableCellPaste: true`） |
+
+### 列宽（表头焦点）
+
+| 按键 | 行为 |
+|------|------|
+| `Alt+←/→` | 键盘调整列宽 |
+| `Shift+Alt+←/→` | 邻列补偿（需 `colResizeDefault: 'shift'`） |
+| `Shift+←/→` | 移动表头焦点列（列拖拽排序辅助） |
+
+### 编辑态
+
+| 按键 | 行为 |
+|------|------|
+| `Esc` | 取消编辑；若正在 async commit 则 `cancelCommit()` |
+| `Enter` | overlay input 策略：提交；overlay 策略由组件处理 |
+| `Tab` | 行编辑模式：同行下一可编辑列 |
+
+---
+
+---
+
 ## 辅助组件
 
 表格列设置（Phase 27）提供一组**独立组件**，对标 AG Grid 的 Side Bar + Columns Tool Panel。只要持有 `GridApi` 即可使用，不强依赖 MagicGrid 内部 DOM。
@@ -1984,7 +2351,7 @@ import {
   ColumnSettingsMenuItem,
   ColumnSettingsMenuIcon,
 } from '@taocompany/magic-grid'
-import type { GridApi, ColumnDef, RowData } from '@taocompany/magic-grid'
+import type { GridApi, ColumnDef, RowData } from '@taocompany/magic-grid/types/core'
 import '@taocompany/magic-grid/style.css'
 
 const columns: ColumnDef[] = [/* ... */]
@@ -2027,7 +2394,7 @@ function onResetColumnOrder(api: GridApi) {
 <script setup lang="ts">
 import { ref } from 'vue'
 import { MagicGrid, ColumnSettingsButton } from '@taocompany/magic-grid'
-import type { GridApi, MagicGridExpose } from '@taocompany/magic-grid'
+import type { GridApi, MagicGridExpose } from '@taocompany/magic-grid/types/core'
 
 const gridRef = ref<MagicGridExpose>()
 </script>
@@ -2260,7 +2627,7 @@ const gridRef = ref<MagicGridExpose>()
 类型 `ColumnSettingsMenuIconName` 已从包导出：
 
 ```ts
-import type { ColumnSettingsMenuIconName } from '@taocompany/magic-grid'
+import type { ColumnSettingsMenuIconName } from '@taocompany/magic-grid/types/core'
 ```
 
 #### Slots / Events / Expose
@@ -2269,14 +2636,214 @@ import type { ColumnSettingsMenuIconName } from '@taocompany/magic-grid'
 
 ---
 
-## 校验子路径
 
-配合 `ColumnDef.validationRules` 使用 async-validator 规则时，可通过子路径导入列 enrich 工具：
+## 包入口与导出
+
+`package.json` `exports` 字段：
+
+| 子路径 | 说明 |
+|--------|------|
+| `@taocompany/magic-grid` | 主入口：组件、编辑器工具、常量、部分 core 工具 |
+| `@taocompany/magic-grid/types/core` | Grid / 列 / 事件 / API 类型（`ColumnDef`、`GridApi`、`MagicGridExpose` 等） |
+| `@taocompany/magic-grid/types/validation` | async-validator 类型别名（`Rule`、`Rules`） |
+| `@taocompany/magic-grid/validation` | 校验运行时（`enrichColumnsWithValidation`、`Schema` 等） |
+| `@taocompany/magic-grid/style.css` | 全局样式（**必须**手动引入） |
+
+### 主入口运行时导出
+
+**组件**
+
+- `MagicGrid`
+- `ColumnSettingsButton` / `ColumnSettingsPanel` / `ColumnSettingsMenuItem` / `ColumnSettingsMenuIcon`
+
+**单元格编辑器**
+
+- `useCellEditor`、`VueCellEditorHost`、`createVueCellEditor`、`createSlotCellEditor`
+- `textCellEditor`、`numberCellEditor`、`checkboxCellEditor`（内置实现，高级场景）
+- `registerCellEditor` / `unregisterCellEditor` / `getCellEditor` / `hasCellEditor` / `getRegisteredCellEditorNames`
+- `BUILTIN_CELL_EDITOR_NAMES`、`isBuiltInCellEditor`
+- `DEFAULT_CELL_EDITOR_MODE`、`resolveCellEditorMode`、`isInlineEditorColumn`
+
+**常量**
+
+- `INDEX_COLUMN_ID`、`DEFAULT_INDEX_COLUMN_START`、`INDEX_COLUMN_MIN_WIDTH`
+- `SELECTION_COLUMN_ID`、`SELECTION_COLUMN_DEFAULT_WIDTH`、`SELECTION_COLUMN_MIN_WIDTH`
+- `DEFAULT_STATUS_BAR_RANGE_AGGREGATION_PRECISION`
+- `COLUMN_DRAG_THRESHOLD_PX`、`SORT_AFTER_MOVE_GUARD_MS`
+
+**工具**
+
+- `toggleHeaderSort`
+- `toBusinessRowId`、`toBusinessRowIdFromInternal`、`toBusinessRowIdsFromInternal`、`isSyntheticRow`
+- `evaluateGridAcceptance`、`getGridAcceptanceThresholds`、`getGridSetDataLimit`（性能验收）
+- `RowMutationPersistError`
+
+---
+
+
+## TypeScript 集成
+
+### 行数据泛型
+
+`ColumnDef` 与 `MagicGridProps` 支持泛型推导列 `prop` 与行数据字段：
 
 ```ts
-import { enrichColumnsWithValidation } from '@taocompany/magic-grid/validation'
+interface UserRow {
+  id: number
+  name: string
+  age: number
+}
+
+const columns: ColumnDef<UserRow>[] = [
+  { prop: 'name', label: '姓名' }, // prop 自动收窄为 'name' | 'age' | 'id'
+]
+
+// MagicGridProps<UserRow> 可用于包装组件 props 类型
+import type { MagicGridProps } from '@taocompany/magic-grid/types/core'
+```
+
+### 组件 ref 类型
+
+```ts
+import type { MagicGridExpose, GridApi } from '@taocompany/magic-grid/types/core'
+
+const gridRef = ref<MagicGridExpose>()
+const api = computed(() => gridRef.value?.api) // Ref<GridApi | undefined>
+```
+
+### 事件 payload
+
+事件回调参数类型均从 `@taocompany/magic-grid/types/core` 导出，例如 `CellValueChangedEvent`、`SelectionChangedEvent`、`FilterModel`、`SortModelItem`。
+
+### 严格模式建议
+
+- 项目启用 `strict: true`；避免对 `RowData` 使用 `any`。
+- 自定义 `cellRenderer` / `valueGetter` 返回值使用 `unknown`，formatter 负责展示字符串。
+
+---
+
+
+## 类型与校验子路径
+
+类型按职责拆分为多个子路径，避免主包体积膨胀。
+
+### `@taocompany/magic-grid/types/core`
+
+Grid / 列 / 事件 / API 的完整类型面。常用导出：
+
+```ts
+import type {
+  // 数据与列
+  RowData,
+  ColumnDef,
+  MagicGridProps,
+  MagicGridExpose,
+  GridApi,
+  RowNode,
+  BusinessRowId,
+  RowIdInput,
+  // 排序 / 筛选
+  SortModelItem,
+  FilterModel,
+  FilterCondition,
+  ColumnFilter,
+  // 编辑
+  CellEditorParams,
+  CellEditorFn,
+  CellEditorDef,
+  CellEditBehavior,
+  CellEditType,
+  CellEditorMode,
+  EditSessionPhase,
+  // 框选
+  CellRange,
+  CellSelectionOptions,
+  CellSelectionAggregation,
+  // 事件（示例）
+  CellValueChangedEvent,
+  SelectionChangedEvent,
+  ColumnMovedEvent,
+  // 校验
+  CellValidator,
+  RowValidator,
+  ValidationRules,
+  GridValidationResult,
+  // 列设置
+  ColumnSettingsResetScope,
+  ColumnSettingsMenuIconName,
+  // 插槽
+  StatusBarContext,
+  DetailRowSlotParams,
+  OverlaySlotParams,
+} from '@taocompany/magic-grid/types/core'
+```
+
+完整列表见源码 `src/types/core.ts`（re-export 聚合）。
+
+### `@taocompany/magic-grid/types/validation`
+
+async-validator 类型透传：
+
+```ts
+import type { Rule, Rules, ValidateError, ValidateFieldsError } from '@taocompany/magic-grid/types/validation'
 ```
 
+### `@taocompany/magic-grid/validation`
+
+校验运行时（需安装 `async-validator` peer dependency）：
+
+```ts
+import {
+  Schema,
+  enrichColumnsWithValidation,
+  createCellValidator,
+  createRowValidator,
+  validateWithSchema,
+  isValidationRequired,
+} from '@taocompany/magic-grid/validation'
+```
+
+---
+
+
+## 本地开发与 Playground
+
+### 环境
+
+```bash
+pnpm install
+pnpm dev          # 启动 Playground（默认 Vite dev server）
+pnpm build        # 构建 npm 包至 dist/
+pnpm test:run     # 单元测试
+pnpm typecheck    # Vue + TS 类型检查
+```
+
+要求 Node.js >= 20.19，包管理器推荐 pnpm 11.x。
+
+### Playground 路由
+
+开发服务器按 Phase 组织演示页，便于逐项验收能力：
+
+| 路由 | 主题 |
+|------|------|
+| `/phase2` – `/phase27` | 各 Phase 功能演示与验收用例 |
+| `/glossary` | 术语表 |
+
+典型入口：`pnpm dev` 后访问控制台输出的本地 URL，从侧边栏切换 Phase。例如列显隐验收 **`/phase22`**（T14–T15 · `available` 列切换）。
+
+Playground 源码位于仓库 `playground/` 目录；自定义 Vue 编辑器示例见 `playground/components/editors/`（Element Plus 集成参考）。
+
+### 构建产物
+
+`pnpm build` 输出：
+
+- `dist/index.es.js` / `dist/index.cjs.js` — 主包
+- `dist/types/*.js` — 类型子路径运行时垫片
+- `dist/style.css` — 样式
+- `dist/*.d.ts` — 类型声明（api-extractor rollup）
+
+发布前会自动执行 `prepublishOnly` → `pnpm run build`。
+
 ---
 
 ## License