@taocompany/magic-grid 0.6.2 → 0.6.4

package/README.md

@@ -294,7 +294,7 @@ const columns: ColumnDef[] = [
 | `indexColumn.width` | `40` | 列宽 px（最小 40） |
 | `indexColumn.start` | `1` | 起始序号 |
 | `indexColumn.focusMode` | `'multiple'` | 辅助定位模式 |
-| `indexColumn.syncToSelectionColumn` | `true` **(MG)** | 索引定位单向同步行选择 |
+| `indexColumn.syncToSelectionColumn` | `true` **(MG)** | 索引定位单向同步行选择；用户点击索引列或 `setIndexFocus`（`mode: 'default'`）时生效 |
 | `indexColumn.showRowDragHandle` | `false` | 不显示行拖拽把柄 |
 | `indexColumn.enableRowResizer` | `false` | 不可拖拽调整行高 |
 
@@ -305,7 +305,7 @@ const columns: ColumnDef[] = [
 | `rowSelection` | `'single'` | 单选模式 |
 | `selectionColumn.width` | `40` | 列宽 px |
 | `selectionColumn.selectAllLabel` | `'全选'` | 全选 checkbox aria-label |
-| `reserveSelection` | `false` | 数据刷新后不保留选中 |
+| `reserveSelection` | `false` | 数据刷新后是否保留选中行；离屏选中可用 `clearRowSelection({ scope: 'all' })` 清空 |
 
 `rowSelection` 对象形式时，`groupSelectsChildren` 默认 `true`（tree 模式父节点级联子孙）。
 
@@ -518,7 +518,7 @@ const columns: ColumnDef[] = [
 | `width` | `number` | `40` | 列宽 px（最小 40） |
 | `start` | `number` | `1` | 起始序号（1-based 展示 = rowIndex + start） |
 | `focusMode` | `'single' \| 'multiple'` | `'multiple'` | 辅助定位模式 |
-| `syncToSelectionColumn` | `boolean` | `false`（MagicGrid 组件层默认 `true`） | 索引列定位是否单向同步到行选择列；仅当 `focusMode` 与 `rowSelection` 同为 single 或同为 multiple 时生效 |
+| `syncToSelectionColumn` | `boolean` | `false`（MagicGrid 组件层默认 `true`） | 索引列定位是否单向同步到行选择列；仅当 `focusMode` 与 `rowSelection` 同为 single 或同为 multiple 时生效。用户在索引列上操作，或 API `setIndexFocus`（`mode: 'default'`）时同步；点击其他区域清除索引定位、行删除 / rowId 迁移等不同步 |
 | `index` | `(rowIndex) => number \| string` | — | 自定义序号展示 |
 | `showRowDragHandle` | `boolean` | `false` | 在索引列显示行拖拽把柄 |
 | `enableRowResizer` | `boolean` | `false` | 索引列底边可拖拽调整行高 |
@@ -531,7 +531,7 @@ const columns: ColumnDef[] = [
 | `rowSelection` | `'single' \| 'multiple' \| false \| RowSelectionConfig` | `'single'` | 行选择模式；`false` 禁用 |
 | `selectionColumn` | `SelectionColumnOptions` | — | 行选择列配置 |
 | `selectable` | `SelectableFn` | — | 行 checkbox 是否可勾选；省略时全部可选 |
-| `reserveSelection` | `boolean` | `false` | 数据刷新后是否保留选中行 |
+| `reserveSelection` | `boolean` | `false` | 数据刷新后是否保留选中行；离屏选中可用 `clearRowSelection({ scope: 'all' })` 清空 |
 | `isRowDisabled` | `boolean \| IsRowDisabledFn` | — | 行级禁用（该行全部数据列 disabled） |
 
 `RowSelectionConfig`：
@@ -974,12 +974,43 @@ api.getColumns().some((c) => c.colId === 'internalCode') // false
 | `width` | `number` | `40` | 列宽 px（最小 40） |
 | `start` | `number` | `1` | 起始序号（1-based 展示 = rowIndex + start） |
 | `focusMode` | `'single' \| 'multiple'` | `'multiple'` | 辅助定位模式 |
-| `syncToSelectionColumn` | `boolean` | core `false` / MagicGrid `true` | 索引列定位单向同步到行选择列 |
+| `syncToSelectionColumn` | `boolean` | core `false` / MagicGrid `true` | 索引列定位单向同步到行选择列；用户点击索引列或 `setIndexFocus`（`mode: 'default'`）时生效 |
 | `index` | `(rowIndex) => number \| string` | — | 自定义序号展示 |
 | `showRowDragHandle` | `boolean` | `false` | 在索引列显示行拖拽把柄 |
 | `enableRowResizer` | `boolean` | `false` | 索引列底边可拖拽调整行高 |
 | `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | `'center'` | 对齐配置 |
 
+### SetIndexFocusOptions
+
+`setIndexFocus` 的可选第二参数：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `mode` | `'default' \| 'manual'` | `'default'` | `default`：与用户点击索引列一致，按 grid `syncToSelectionColumn` 决定是否同步行选择列；`manual`：由 `syncToSelectionColumn` 显式控制 |
+| `syncToSelectionColumn` | `boolean` | `false`（仅 `mode: 'manual'` 时生效） | 是否同步行选择列；可覆盖 grid 配置 |
+
+```ts
+api.setIndexFocus(2)                                              // 默认模式
+api.setIndexFocus(2, { mode: 'default' })                       // 同上
+api.setIndexFocus(2, { mode: 'manual', syncToSelectionColumn: false })  // 仅定位，不选中
+api.setIndexFocus(2, { mode: 'manual', syncToSelectionColumn: true })   // 强制同步选中
+api.setIndexFocus([])                                             // 清除定位
+```
+
+### ClearRowSelectionOptions
+
+`clearRowSelection` 的可选参数：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `scope` | `'current' \| 'all'` | `'all'` | `all`：清空全部选中（含 `reserveSelection` 离屏选中）；`current`：仅取消当前 display 中的选中 |
+
+```ts
+api.clearRowSelection()                        // 清空全部
+api.clearRowSelection({ scope: 'all' })        // 同上
+api.clearRowSelection({ scope: 'current' })    // 仅清当前可见 display 中的选中
+```
+
 ### SelectionColumnOptions
 
 行选择列配置，通过 `selectionColumn` prop 传入（`rowSelection !== false` 时生效）。
@@ -1348,6 +1379,59 @@ api.clearAllFilters()
 
 MagicGrid 通过 Vue 事件向外暴露 Grid 内核事件。事件名采用 **kebab-case**。除 Vue 事件外，也可通过 `gridRef.value?.api.on(...)` 订阅 camelCase 内核事件（见 [Expose](#expose)）。
 
+完整 payload 类型定义与 JSDoc 见源码 `src/core/types/events.ts`；下列说明与之一致。
+
+### Payload 约定
+
+#### 订阅方式
+
+| 场景 | 写法 | 事件名 |
+|------|------|--------|
+| `GridApi` | `api.on('cellClicked', handler)` | camelCase |
+| `MagicGrid` | `@cell-clicked="handler"` | kebab-case |
+
+#### 泛型 `TData` / `TValue`
+
+多数带行/格数据的 payload 支持泛型，与 `MagicGridProps<TData>`、`ColumnDef<TData>` 对齐：
+
+| 泛型 | 含义 | 默认 |
+|------|------|------|
+| `TData` | 业务行类型 | `RowData` |
+| `TValue` | 单元格**原始值**类型（经 `valueGetter`，**不含** `formatter`） | `unknown` |
+
+Handler 标注示例：
+
+```ts
+interface UserRow {
+  id: number
+  name: string
+}
+
+function onRowClick(event: RowClickedEvent<UserRow>) {
+  event.data.name // 无需 event.rowNode.data
+}
+
+function onCellChange(event: CellValueChangedEvent<UserRow, number>) {
+  event.oldValue
+  event.newValue
+}
+```
+
+#### 常用字段
+
+| 字段 | 说明 |
+|------|------|
+| `rowId`（`BusinessRowId`） | 业务主键，通常等于 `data[rowKey]`；临时行（`__mg_tmp_*`）为 `null` |
+| `data` | 行数据快照，规则同 `api.getData()`（浅拷贝；临时行 `rowKey` 字段为 `null`）。**优先用 `event.data` 读业务字段** |
+| `rowNode` | 内核行节点，含布局/分组/树形等运行时字段；`data` 不够用时再用 |
+| `value` / `oldValue` / `newValue` | 单元格原始值，与排序/过滤/编辑管线同源，**不是** formatter 展示文本 |
+| `rowIndex` | 在 `rowsToDisplay`（筛选/分组/排序后可见行）中的下标 |
+| `colId` | 列 id：`column.key ?? column.prop ?? 'col_${index}'` |
+
+`RowEditChange<TValue>` 用于行级 `changes` 数组，含 `colId`、`oldValue`、`newValue`。
+
+`EditingCellPosition<TData, TValue>` 为 `api.getEditingCells()` 返回值元素，含 `data` / `value`。
+
 ### 生命周期
 
 | Vue 事件 | 内核事件 | 频率 | 说明 |
@@ -1420,6 +1504,10 @@ function onGridReady({ api }: GridReadyEvent) {
 
 #### `cell-clicked`
 
+表体单元格 **mousedown** 时触发（框选、索引/选择列纵向拖选等交互的起点）。MagicGrid：`@cell-clicked` · Api：`cellClicked`。
+
+与 `row-click` 区别：本事件在 **按下** 时触发且覆盖所有表体格；`row-click` 在 **click** 阶段且仅 leaf 数据行。
+
 payload 为 `CellClickedEvent<TData, TValue>`（默认 `TData = RowData`，`TValue = unknown`）：
 
 | 字段 | 类型 | 说明 |
@@ -1433,6 +1521,10 @@ payload 为 `CellClickedEvent<TData, TValue>`（默认 `TData = RowData`，`TVal
 
 #### `row-click` / `row-dblclick`
 
+表体 **leaf 数据行** 在 **click / dblclick** 阶段触发；不含分组头、详情行、表尾汇总行。典型用途：行级导航、打开侧栏。需要单元格值时用 `cell-clicked`。
+
+MagicGrid：`@row-click` / `@row-dblclick` · Api：`rowClicked` / `rowDoubleClicked`。
+
 payload 为 `RowClickedEvent<TData>` / `RowDoubleClickedEvent<TData>`（默认 `TData = RowData`）：
 
 | 字段 | 类型 | 说明 |
@@ -1443,10 +1535,10 @@ payload 为 `RowClickedEvent<TData>` / `RowDoubleClickedEvent<TData>`（默认 `
 | `data` | `TData` | 行数据快照（与 `getData` 导出规则一致） |
 | `colId` | `string` | 触发点击/双击的列 id |
 
-> 不含分组头行、详情行、表尾汇总行。
-
 #### `selection-changed`
 
+行选择列 checkbox 选中集变化时触发。MagicGrid：`@selection-changed`。仅反映 checkbox 勾选，不含索引列定位（见 `index-focus-changed`）。也可通过 `api.getSelectedRowIds()` 同步读取当前选中。
+
 payload 为 `SelectionChangedEvent`：
 
 | 字段 | 类型 | 说明 |
@@ -1455,16 +1547,26 @@ payload 为 `SelectionChangedEvent`：
 
 #### `index-focus-changed`
 
+索引列辅助定位变化时触发。MagicGrid：`@index-focus-changed`。与 checkbox 选中（`selection-changed`）独立。也可通过 `api.getIndexFocusedRowIds()` 同步读取当前定位。
+
 payload 为 `IndexFocusChangedEvent`：
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `focusedRowIds` | `BusinessRowId[]` | 索引列辅助定位的行 id 列表 |
 
+#### `cell-focused`
+
+键盘/指针导航导致焦点格变化时触发。**仅 Api：`cellFocused`**（MagicGrid 未转发）。表示输入焦点所在格，不等同于 checkbox 选中或索引列定位。
+
+payload 为 `CellFocusedEvent<TData, TValue>`（默认 `TData = RowData`，`TValue = unknown`；字段同 `cell-clicked`：`rowId`、`colId`、`rowIndex`、`rowNode`、`data`、`value`）。
+
 ### 编辑
 
 #### `cell-editing-started`
 
+单元格进入 **overlay 编辑态** 时触发（不含 inline checkbox/switch）。行编辑模式下每列各触发一次。MagicGrid：`@cell-editing-started`。
+
 payload 为 `CellEditingStartedEvent<TData, TValue>`（默认 `TData = RowData`，`TValue = unknown`）：
 
 | 字段 | 类型 | 说明 |
@@ -1477,6 +1579,11 @@ payload 为 `CellEditingStartedEvent<TData, TValue>`（默认 `TData = RowData`
 
 #### `cell-editing-stopped`
 
+单元格退出 overlay 编辑态（提交或取消）时触发。MagicGrid：`@cell-editing-stopped`。
+
+- `committed: true`：走提交路径结束（可能因校验失败未写回，见 `cell-validation-failed`）
+- `committed: false`：Esc / `stopEditing(true)` 取消；`newValue` 多为 `undefined`
+
 payload 为 `CellEditingStoppedEvent<TData, TValue>`（默认 `TData = RowData`，`TValue = unknown`）：
 
 | 字段 | 类型 | 说明 |
@@ -1488,6 +1595,8 @@ payload 为 `CellEditingStoppedEvent<TData, TValue>`（默认 `TData = RowData`
 
 #### `cell-value-changed`
 
+单元格值**已成功写回** `row.data` 后触发（编辑提交、inline toggle、粘贴、框选填充/删除等）。仅在实际变更时触发；取消编辑不触发。行编辑模式下每列各触发一次。MagicGrid：`@cell-value-changed`。
+
 payload 为 `CellValueChangedEvent<TData, TValue>`（默认 `TData = RowData`，`TValue = unknown`）：
 
 | 字段 | 类型 | 说明 |
@@ -1499,22 +1608,22 @@ payload 为 `CellValueChangedEvent<TData, TValue>`（默认 `TData = RowData`，
 
 #### `cell-commit-started` / `cell-commit-finished`
 
-异步提交生命周期：
+单元格**异步提交**生命周期（`asyncRowMutation` 等）。`cellCommitStarted` 在 `cellValueChanged` 之前。MagicGrid：`@cell-commit-finished`。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `rowId` / `colId` / `rowIndex` | — | 格位置 |
-| `committed` | `boolean` | （finished）是否成功提交 |
-| `aborted` | `boolean` | （finished）是否被中断 |
+| `committed` | `boolean` | （finished）是否成功提交并写回 |
+| `aborted` | `boolean` | （finished）是否被 `cancelCommit()` 等中断 |
 
 #### `edit-commit-aborted`
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `rowId` / `colId` / `rowIndex` | 可选 | 被中断的编辑格 |
+编辑提交被主动中断时触发（如 `cancelCommit()`）。MagicGrid：`@edit-commit-aborted`。字段均可选。
 
 #### `row-editing-started`
 
+行编辑模式（`editBehavior: 'row'`）整行进入编辑时触发；同行多列 editor 同时 mount，各列还会各发 `cell-editing-started`。MagicGrid：`@row-editing-started`。
+
 payload 为 `RowEditingStartedEvent<TData>`（默认 `TData = RowData`）：
 
 | 字段 | 类型 | 说明 |
@@ -1525,6 +1634,10 @@ payload 为 `RowEditingStartedEvent<TData>`（默认 `TData = RowData`）：
 
 #### `row-editing-stopped`
 
+行编辑模式整行退出编辑时触发。MagicGrid：`@row-editing-stopped`。
+
+`changes` 仅在 `committed: true` 且存在实际值差异时出现。监听写回后的业务数据优先用 `row-value-changed`。
+
 payload 为 `RowEditingStoppedEvent<TData, TValue>`（默认 `TData = RowData`，`TValue = unknown`）：
 
 | 字段 | 类型 | 说明 |
@@ -1532,10 +1645,12 @@ payload 为 `RowEditingStoppedEvent<TData, TValue>`（默认 `TData = RowData`
 | `rowId` / `rowIndex` | — | 行位置 |
 | `committed` | `boolean` | 是否成功提交 |
 | `data` | `TData` | 行数据快照（与 `getData` 导出规则一致） |
-| `changes` | `RowEditChange<TValue>[]` | 变更列列表（`colId` / `oldValue` / `newValue`） |
+| `changes` | `RowEditChange<TValue>[]` | 列级变更摘要；取消或未变更时为 `undefined` |
 
 #### `row-value-changed`
 
+行编辑**整行提交成功且至少一列发生变化**时触发；单格编辑不触发。比 `row-editing-stopped` 更贴近「业务数据已更新」。MagicGrid：`@row-value-changed`。
+
 payload 为 `RowValueChangedEvent<TData, TValue>`（默认 `TData = RowData`，`TValue = unknown`）：
 
 | 字段 | 类型 | 说明 |
@@ -1547,12 +1662,16 @@ payload 为 `RowValueChangedEvent<TData, TValue>`（默认 `TData = RowData`，`
 
 #### `row-commit-started` / `row-commit-finished`
 
-payload 为 `RowCommitStartedEvent<TData>` / `RowCommitFinishedEvent<TData>`（默认 `TData = RowData`）；含 `data` 行数据快照，字段语义同行级异步提交。
+行编辑**异步整行提交**生命周期。MagicGrid：`@row-commit-started` / `@row-commit-finished`。
+
+payload 为 `RowCommitStartedEvent<TData>` / `RowCommitFinishedEvent<TData>`（默认 `TData = RowData`）；含 `data` 行数据快照。
 
 ### 校验
 
 #### `cell-validation-failed`
 
+单元格编辑校验失败时触发。MagicGrid：`@cell-validation-failed`。`mode` 对应 `invalidEditValueMode`：`block` / `revert` / `keep`。
+
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `rowId` / `colId` / `rowIndex` | — | 格位置 |
@@ -1561,6 +1680,8 @@ payload 为 `RowCommitStartedEvent<TData>` / `RowCommitFinishedEvent<TData>`（
 
 #### `row-validation-failed`
 
+行编辑整行校验失败时触发。MagicGrid：`@row-validation-failed`。`cellErrors` 为列级错误；`rowErrors` 为 `rowValidator` 行级错误。
+
 payload 为 `RowValidationFailedEvent<TData>`（默认 `TData = RowData`）：
 
 | 字段 | 类型 | 说明 |
@@ -1790,11 +1911,34 @@ payload 为 `RowExpansionChangedEvent`：
 ### 事件监听示例
 
 ```vue
-<MagicGrid
-  @cell-value-changed="({ rowId, colId, newValue, oldValue }) => { ... }"
-  @sort-changed="(model) => { ... }"
-  @filter-changed="(model) => { ... }"
-/>
+<script setup lang="ts">
+import type { CellValueChangedEvent, RowClickedEvent } from '@taocompany/magic-grid/types/core'
+
+interface UserRow {
+  id: number
+  name: string
+  score: number
+}
+
+function onCellValueChanged(event: CellValueChangedEvent<UserRow, number>) {
+  console.log(event.data.name, event.oldValue, event.newValue)
+}
+
+function onRowClick(event: RowClickedEvent<UserRow>) {
+  console.log(event.data, event.colId)
+}
+</script>
+
+<template>
+  <MagicGrid
+    :columns="columns"
+    :data="rows"
+    @cell-value-changed="onCellValueChanged"
+    @row-click="onRowClick"
+    @sort-changed="(model) => { ... }"
+    @filter-changed="(model) => { ... }"
+  />
+</template>
 ```
 
 ---
@@ -1974,11 +2118,48 @@ async function addRow() {
 
 #### 行选择 / 索引定位
 
-| 方法 | 参数 | 说明 |
-|------|------|------|
-| `toggleRowSelection(rowIds, selected?, force?)` | selected 省略时 toggle | 切换/设置 checkbox 选中 |
-| `toggleAllSelection(selected?)` | 仅 multiple 模式 | 表头全选操作 |
-| `setIndexFocus(rowIds)` | — | 设置索引列辅助定位 |
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `toggleRowSelection(rowIds, selected?, force?)` | selected 省略时 toggle | `void` | 切换/设置 checkbox 选中；变更时 emit `selectionChanged` |
+| `toggleAllSelection(selected?)` | 仅 multiple 模式 | `void` | 表头全选操作；`false` 仅取消可见可选行，保留 disabled 已选行 |
+| `clearRowSelection(options?)` | `ClearRowSelectionOptions` | `void` | 清空行 checkbox 选中；变更时 emit `selectionChanged` |
+| `getSelectedRowIds()` | — | `BusinessRowId[]` | 读取当前 checkbox 选中（与 `selectionChanged.selectedRowIds` 同型） |
+| `setIndexFocus(rowIds, options?)` | `SetIndexFocusOptions` | `void` | 编程式设置索引列辅助定位，不进入鼠标拖拉；变更时 emit `indexFocusChanged` |
+| `getIndexFocusedRowIds()` | — | `BusinessRowId[]` | 读取当前索引列辅助定位；未启用 `showIndexColumn` 时返回 `[]` |
+
+**`clearRowSelection`**
+
+| `options.scope` | 行为 |
+|-----------------|------|
+| `'all'`（默认） | 清空全部选中，含 `reserveSelection` 保留的离屏选中 |
+| `'current'` | 仅取消当前 display 中的选中，保留离屏选中 |
+
+**`setIndexFocus`**
+
+须启用 `showIndexColumn`。`focusMode: 'single'` 时仅保留首个有效 id。
+
+| `options.mode` | 同步行选择列 |
+|----------------|-------------|
+| `'default'`（默认） | 与用户点击索引列一致，按 `indexColumn.syncToSelectionColumn` 决定 |
+| `'manual'` | 由 `syncToSelectionColumn` 显式控制（可覆盖 grid 配置；省略时视为 `false`） |
+
+```ts
+// 行选择
+api.toggleRowSelection([1, 3], true)
+api.getSelectedRowIds()                         // => [1, 3]
+api.clearRowSelection()                         // 清空全部（含离屏）
+api.clearRowSelection({ scope: 'current' })     // 仅清当前 display
+
+// 索引定位
+api.setIndexFocus(2)
+api.setIndexFocus([1, 2, 3])                    // multiple 模式
+api.setIndexFocus([])                           // 清除
+api.getIndexFocusedRowIds()                     // => [2]
+
+api.setIndexFocus(2, { mode: 'manual', syncToSelectionColumn: false })  // 仅定位
+```
+
+类型 `SetIndexFocusOptions`、`ClearRowSelectionOptions` 见 [Options 类型参考](#options-类型参考)。
 
 #### 展开 / 分组 / 树
 
@@ -2020,13 +2201,23 @@ GridApi 支持 `on(eventType, handler)` 订阅内核事件（camelCase），返
 | `gridReady` | `grid-ready` |
 | `gridDestroyed` | `grid-destroyed` |
 | `firstRendered` | `first-rendered` |
+| `cellClicked` | `cell-clicked` |
+| `rowClicked` | `row-click` |
+| `rowDoubleClicked` | `row-dblclick` |
 | `selectionChanged` | `selection-changed` |
+| `indexFocusChanged` | `index-focus-changed` |
 | `cellValueChanged` | `cell-value-changed` |
+| `cellEditingStarted` | `cell-editing-started` |
+| `cellEditingStopped` | `cell-editing-stopped` |
+| `rowEditingStarted` | `row-editing-started` |
+| `rowEditingStopped` | `row-editing-stopped` |
+| `rowValueChanged` | `row-value-changed` |
 | `sortChanged` | `sort-changed` |
 | `filterChanged` | `filter-changed` |
 | `columnMoved` | `column-moved` |
 | `cellSelectionChanged` | `cell-selection-changed` |
-| … | 其余见 [Events](#events) |
+| `cellFocused` | （MagicGrid 未转发，仅 Api） |
+| … | 其余见 [Events](#events) 与 `src/core/types/events.ts` |
 
 ```ts
 const api = gridRef.value?.api
@@ -2036,11 +2227,12 @@ const off = api?.on('selectionChanged', (event) => {
 off?.() // 取消订阅
 ```
 
-### rowId 约定
+### rowId 与事件 data
 
 - **入参**：接受 `string | number`，与 `data[rowKey]` 类型一致；API 边界自动 `String()`。
-- **出参 / 事件**：内核 rowId 恒为 `string`（与 DOM `data-row-id` 一致）。
-- **临时行**：新增时省略 `rowKey` 或值为 `null` 时生成 `__mg_tmp_*` 内部 id；`getData()` 导出时对应字段为 `null`。
+- **出参 / 事件 `rowId`**：对外投影为 `BusinessRowId`（`string | number | null`），与 `data[rowKey]` 同型。
+- **临时行**：新增时省略 `rowKey` 或值为 `null` 时生成 `__mg_tmp_*` 内部 id；事件 `rowId` 为 `null`，`getData()` / 事件 `data[rowKey]` 亦为 `null`。
+- **事件 `data`**：行数据快照，规则同 `getData()`；handler 中优先读 `event.data`，不必 `event.rowNode.data`。
 
 ---
 
@@ -3146,7 +3338,42 @@ const gridRef = ref<MagicGridExpose>()
 
 ### 事件 payload
 
-事件回调参数类型均从 `@taocompany/magic-grid/types/core` 导出，例如 `GridReadyEvent`、`CellValueChangedEvent`、`FilterModel`。
+事件回调参数类型均从 `@taocompany/magic-grid/types/core` 导出。定义与 JSDoc 以 `src/core/types/events.ts` 为准。
+
+带业务类型的 handler 标注示例：
+
+```ts
+import type {
+  CellClickedEvent,
+  CellEditingStoppedEvent,
+  CellValueChangedEvent,
+  EditingCellPosition,
+  RowClickedEvent,
+  RowEditChange,
+  RowValueChangedEvent,
+} from '@taocompany/magic-grid/types/core'
+
+interface OrderRow {
+  id: string
+  amount: number
+}
+
+// 交互
+const onRowClick = (e: RowClickedEvent<OrderRow>) => e.data.id
+const onCellClick = (e: CellClickedEvent<OrderRow, number>) => e.value
+
+// 编辑
+const onEditStop = (e: CellEditingStoppedEvent<OrderRow, number>) => e.oldValue
+const onValueChanged = (e: CellValueChangedEvent<OrderRow, number>) => e.newValue
+const onRowChanged = (e: RowValueChangedEvent<OrderRow, number>) => {
+  const change: RowEditChange<number> | undefined = e.changes[0]
+}
+
+// API
+const cells: EditingCellPosition<OrderRow, unknown>[] = api.getEditingCells()
+```
+
+常用导出：`GridReadyEvent`、`CellValueChangedEvent`、`RowClickedEvent`、`FilterModel`、`GridEventMap`、`GridEventHandler`、`SetIndexFocusOptions`、`ClearRowSelectionOptions`、`BusinessRowId`。
 
 ### 严格模式建议
 
@@ -3193,7 +3420,20 @@ import type {
   CellSelectionOptions,
   CellSelectionAggregation,
   // 事件（示例）
+  RowClickedEvent,
+  RowDoubleClickedEvent,
+  CellClickedEvent,
+  CellFocusedEvent,
   CellValueChangedEvent,
+  CellEditingStartedEvent,
+  CellEditingStoppedEvent,
+  RowEditingStartedEvent,
+  RowEditingStoppedEvent,
+  RowValueChangedEvent,
+  RowEditChange,
+  EditingCellPosition,
+  GridEventMap,
+  GridEventHandler,
   SelectionChangedEvent,
   ColumnMovedEvent,
   // 校验

package/dist/cellEditorCache-DmICiO9q.js.map

@@ -1 +1 @@
-{"version":3,"file":"cellEditorCache-DmICiO9q.js","names":[],"sources":["../src/core/types/indexColumn.ts","../src/core/types/rowSelectionOptions.ts","../src/core/types/selectionColumn.ts","../src/core/types/cellEditorMode.ts","../src/core/types/cellEditorCache.ts"],"sourcesContent":["import type { ColumnDef } from '@types'\r\nimport type { GridHorizontalAlign, GridVerticalAlign } from '@core/types/align'\r\n\r\n/** 系统索引列 colId；用户 columns 不得占用 */\r\nexport const INDEX_COLUMN_ID = '__index__'\r\n\r\n/** 索引列最小（默认）宽度 px */\r\nexport const INDEX_COLUMN_MIN_WIDTH = 40\r\n\r\n/** 索引列默认起始序号（1-based 展示 = rowIndex + start） */\r\nexport const DEFAULT_INDEX_COLUMN_START = 1\r\n\r\n/** 索引列配置 */\r\nexport interface IndexColumnOptions {\r\n  /** 表头文案；默认空字符串 */\r\n  label?: string\r\n  /** 列宽 px；默认 40；小于 40 时钳制为 40 */\r\n  width?: number\r\n  /** 起始序号（1-based 展示 = rowIndex + start）；默认 1 */\r\n  start?: number\r\n  /**\r\n   * 辅助定位模式：single / multiple（multiple 支持 Ctrl/Shift/拖拉范围）\r\n   * 默认 multiple（Excel 行号式交互）\r\n   */\r\n  focusMode?: 'single' | 'multiple'\r\n  /**\r\n   * 索引列定位是否单向同步到行选择列（业务选中）；core 默认 false，MagicGrid 组件层默认 true。\r\n   * 仅当 indexColumn.focusMode 与 rowSelection 同为 single 或同为 multiple 时生效。\r\n   * 仅用户在索引列上操作（点击/拖选/再次点击取消）时同步；点击其他区域清除索引定位不同步行选择列。\r\n   */\r\n  syncToSelectionColumn?: boolean\r\n  /** 表头水平对齐；默认 center */\r\n  headerAlign?: GridHorizontalAlign\r\n  /** 表头垂直对齐；默认 center */\r\n  headerValign?: GridVerticalAlign\r\n  /** 表体水平对齐；默认 center */\r\n  align?: GridHorizontalAlign\r\n  /** 表体垂直对齐；默认 center */\r\n  valign?: GridVerticalAlign\r\n  /** footer 水平对齐；默认 center */\r\n  footerAlign?: GridHorizontalAlign\r\n  /** footer 垂直对齐；默认 center */\r\n  footerValign?: GridVerticalAlign\r\n  /**\r\n   * 自定义序号展示；入参为 rowsToDisplay 下标。\r\n   * 缺省：(rowIndex) => String(rowIndex + start)\r\n   */\r\n  index?: (rowIndex: number) => number | string\r\n  /**\r\n   * 在索引列 cell 内显示行拖拽把柄；默认 false。\r\n   * 需配合 Grid `rowDragManaged` 或监听 `rowDragEnd` 自行改序。\r\n   */\r\n  showRowDragHandle?: boolean\r\n  /**\r\n   * 索引列底边可拖拽调整行高；默认 false。\r\n   * 对标 AG Grid Row Numbers `enableRowResizer`。\r\n   */\r\n  enableRowResizer?: boolean\r\n}\r\n\r\n/** Grid 级索引列开关与配置（块 0 类型；块 1+ 消费） */\r\nexport interface IndexColumnGridOptions {\r\n  /** 是否显示最左侧索引列；默认 false */\r\n  showIndexColumn?: boolean\r\n  /** 索引列配置；showIndexColumn=true 时生效 */\r\n  indexColumn?: IndexColumnOptions\r\n}\r\n\r\nexport interface ResolvedIndexColumnOptions {\r\n  label: string\r\n  width: number\r\n  start: number\r\n  focusMode: 'single' | 'multiple'\r\n  syncToSelectionColumn: boolean\r\n  showRowDragHandle: boolean\r\n  enableRowResizer: boolean\r\n  headerAlign: GridHorizontalAlign\r\n  headerValign: GridVerticalAlign\r\n  align: GridHorizontalAlign\r\n  valign: GridVerticalAlign\r\n  footerAlign: GridHorizontalAlign\r\n  footerValign: GridVerticalAlign\r\n  index?: (rowIndex: number) => number | string\r\n}\r\n\r\nexport interface ResolvedIndexColumnGridOptions {\r\n  showIndexColumn: boolean\r\n  indexColumn: ResolvedIndexColumnOptions\r\n}\r\n\r\nexport function resolveIndexColumnWidth(width?: number): number {\r\n  return Math.max(INDEX_COLUMN_MIN_WIDTH, width ?? INDEX_COLUMN_MIN_WIDTH)\r\n}\r\n\r\nexport function resolveIndexColumnOptions(\r\n  options: IndexColumnOptions = {},\r\n): ResolvedIndexColumnOptions {\r\n  return {\r\n    label: options.label ?? '',\r\n    width: resolveIndexColumnWidth(options.width),\r\n    start: options.start ?? DEFAULT_INDEX_COLUMN_START,\r\n    focusMode: options.focusMode === 'single' ? 'single' : 'multiple',\r\n    syncToSelectionColumn: options.syncToSelectionColumn ?? false,\r\n    showRowDragHandle: options.showRowDragHandle ?? false,\r\n    enableRowResizer: options.enableRowResizer ?? false,\r\n    headerAlign: options.headerAlign ?? 'center',\r\n    headerValign: options.headerValign ?? 'center',\r\n    align: options.align ?? 'center',\r\n    valign: options.valign ?? 'center',\r\n    footerAlign: options.footerAlign ?? 'center',\r\n    footerValign: options.footerValign ?? 'center',\r\n    index: options.index,\r\n  }\r\n}\r\n\r\nexport function resolveIndexColumnGridOptions(\r\n  options: IndexColumnGridOptions = {},\r\n): ResolvedIndexColumnGridOptions {\r\n  return {\r\n    showIndexColumn: options.showIndexColumn ?? false,\r\n    indexColumn: resolveIndexColumnOptions(options.indexColumn),\r\n  }\r\n}\r\n\r\nexport function isIndexColumn(colId: string): boolean {\r\n  return colId === INDEX_COLUMN_ID\r\n}\r\n\r\nexport function resolveColumnDefColId(column: ColumnDef, index: number): string {\r\n  return column.key ?? column.prop ?? `col_${index}`\r\n}\r\n\r\n/** 开发模式：用户 columns 占用系统索引列 colId 时告警 */\r\nexport function warnIfUserColumnsConflictWithIndexColumn(\r\n  columns: readonly ColumnDef[],\r\n): void {\r\n  if (!import.meta.env.DEV) {\r\n    return\r\n  }\r\n\r\n  columns.forEach((column, index) => {\r\n    const colId = resolveColumnDefColId(column, index)\r\n    if (colId === INDEX_COLUMN_ID || column.key === INDEX_COLUMN_ID) {\r\n      console.warn(\r\n        `[magic-grid] Column \"${INDEX_COLUMN_ID}\" is reserved for the system index column. ` +\r\n          'Remove it from your columns definition or use showIndexColumn instead.',\r\n      )\r\n    }\r\n  })\r\n}\r\n","export type RowSelectionMode = 'single' | 'multiple'\n\n/** 行选择配置（Phase 19 · groupSelectsChildren） */\nexport interface RowSelectionConfig {\n  mode: RowSelectionMode\n  /**\n   * tree 模式下选中父节点是否级联选中子孙。默认 `true`。\n   * 对标 AG Grid rowSelection.groupSelectsChildren。\n   */\n  groupSelectsChildren?: boolean\n}\n\nexport type RowSelectionInput =\n  | RowSelectionMode\n  | false\n  | RowSelectionConfig\n\nexport interface ResolvedRowSelectionOptions {\n  mode: RowSelectionMode | false\n  groupSelectsChildren: boolean\n}\n\nexport function normalizeRowSelectionInput(\n  input: RowSelectionInput | undefined,\n): ResolvedRowSelectionOptions {\n  if (input === false) {\n    return { mode: false, groupSelectsChildren: true }\n  }\n\n  if (input == null) {\n    return { mode: 'single', groupSelectsChildren: true }\n  }\n\n  if (typeof input === 'string') {\n    return {\n      mode: input === 'multiple' ? 'multiple' : 'single',\n      groupSelectsChildren: true,\n    }\n  }\n\n  return {\n    mode: input.mode === 'multiple' ? 'multiple' : 'single',\n    groupSelectsChildren: input.groupSelectsChildren ?? true,\n  }\n}\n\nexport function normalizeRowSelectionMode(\n  resolved: ResolvedRowSelectionOptions,\n): RowSelectionMode | false {\n  return resolved.mode\n}\n","import type { RowSelectionMode } from '@core/selection/selectionService'\r\nimport {\r\n  normalizeRowSelectionInput,\r\n  type RowSelectionInput,\r\n} from '@core/types/rowSelectionOptions'\r\n\r\nimport { resolveColumnDefColId } from './indexColumn'\r\nimport type { GridHorizontalAlign, GridVerticalAlign } from '@core/types/align'\r\nimport type { ColumnDef } from '@types'\r\n\r\n/** 系统行选择列 colId；用户 columns 不得占用 */\r\nexport const SELECTION_COLUMN_ID = '__select__'\r\n\r\n/** 行选择列最小宽度 px */\r\nexport const SELECTION_COLUMN_MIN_WIDTH = 40\r\n\r\n/** 行选择列默认宽度 px */\r\nexport const SELECTION_COLUMN_DEFAULT_WIDTH = 40\r\n\r\n/** 表头全选 checkbox 默认 aria-label */\r\nexport const DEFAULT_SELECTION_SELECT_ALL_LABEL = '全选'\r\n\r\n/** 行选择列配置 */\r\nexport interface SelectionColumnOptions {\r\n  /** 列宽 px；默认 40；小于 40 时钳制为 40 */\r\n  width?: number\r\n  /** 表头全选 checkbox 的 aria-label；默认「全选」 */\r\n  selectAllLabel?: string\r\n  /** 行 checkbox 的 aria-label 工厂 */\r\n  rowLabel?: (rowIndex: number) => string\r\n  /** 表头水平对齐；默认 center */\r\n  headerAlign?: GridHorizontalAlign\r\n  /** 表头垂直对齐；默认 center */\r\n  headerValign?: GridVerticalAlign\r\n  /** 表体水平对齐；默认 center */\r\n  align?: GridHorizontalAlign\r\n  /** 表体垂直对齐；默认 center */\r\n  valign?: GridVerticalAlign\r\n  /** footer 水平对齐；默认 center */\r\n  footerAlign?: GridHorizontalAlign\r\n  /** footer 垂直对齐；默认 center */\r\n  footerValign?: GridVerticalAlign\r\n}\r\n\r\n/** Grid 级行选择列配置（块 0 类型；块 1+ 消费） */\r\nexport interface SelectionColumnGridOptions {\r\n  /** 行选择列配置；rowSelection !== false 时生效 */\r\n  selectionColumn?: SelectionColumnOptions\r\n}\r\n\r\nexport interface ResolvedSelectionColumnOptions {\r\n  width: number\r\n  selectAllLabel: string\r\n  rowLabel?: (rowIndex: number) => string\r\n  headerAlign: GridHorizontalAlign\r\n  headerValign: GridVerticalAlign\r\n  align: GridHorizontalAlign\r\n  valign: GridVerticalAlign\r\n  footerAlign: GridHorizontalAlign\r\n  footerValign: GridVerticalAlign\r\n}\r\n\r\nexport interface ResolvedSelectionColumnGridOptions {\r\n  /** rowSelection !== false */\r\n  enabled: boolean\r\n  /** 行选模式；enabled=false 时为占位 single */\r\n  mode: RowSelectionMode\r\n  selectionColumn: ResolvedSelectionColumnOptions\r\n}\r\n\r\nexport function resolveSelectionColumnWidth(width?: number): number {\r\n  return Math.max(SELECTION_COLUMN_MIN_WIDTH, width ?? SELECTION_COLUMN_DEFAULT_WIDTH)\r\n}\r\n\r\nexport function resolveSelectionColumnOptions(\r\n  options: SelectionColumnOptions = {},\r\n): ResolvedSelectionColumnOptions {\r\n  return {\r\n    width: resolveSelectionColumnWidth(options.width),\r\n    selectAllLabel: options.selectAllLabel ?? DEFAULT_SELECTION_SELECT_ALL_LABEL,\r\n    rowLabel: options.rowLabel,\r\n    headerAlign: options.headerAlign ?? 'center',\r\n    headerValign: options.headerValign ?? 'center',\r\n    align: options.align ?? 'center',\r\n    valign: options.valign ?? 'center',\r\n    footerAlign: options.footerAlign ?? 'center',\r\n    footerValign: options.footerValign ?? 'center',\r\n  }\r\n}\r\n\r\nexport function resolveSelectionColumnGridOptions(\r\n  options: {\r\n    rowSelection?: RowSelectionInput\r\n    selectionColumn?: SelectionColumnOptions\r\n  } = {},\r\n): ResolvedSelectionColumnGridOptions {\r\n  // Grid 直建时缺省 rowSelection 仍不注入行选择列；MagicGrid 默认传 'single'。\r\n  if (options.rowSelection == null) {\r\n    return {\r\n      enabled: false,\r\n      mode: 'single',\r\n      selectionColumn: resolveSelectionColumnOptions(options.selectionColumn),\r\n    }\r\n  }\r\n\r\n  const resolved = normalizeRowSelectionInput(options.rowSelection)\r\n  const enabled = resolved.mode !== false\r\n\r\n  return {\r\n    enabled,\r\n    mode: enabled && resolved.mode !== false ? resolved.mode : 'single',\r\n    selectionColumn: resolveSelectionColumnOptions(options.selectionColumn),\r\n  }\r\n}\r\n\r\nexport function isSelectionColumn(colId: string): boolean {\r\n  return colId === SELECTION_COLUMN_ID\r\n}\r\n\r\n/** 开发模式：用户 columns 占用系统行选择列 colId 时告警 */\r\nexport function warnIfUserColumnsConflictWithSelectionColumn(\r\n  columns: readonly ColumnDef[],\r\n): void {\r\n  if (!import.meta.env.DEV) {\r\n    return\r\n  }\r\n\r\n  columns.forEach((column, index) => {\r\n    const colId = resolveColumnDefColId(column, index)\r\n    if (colId === SELECTION_COLUMN_ID || column.key === SELECTION_COLUMN_ID) {\r\n      console.warn(\r\n        `[magic-grid] Column \"${SELECTION_COLUMN_ID}\" is reserved for the system row selection column. ` +\r\n          'Remove it from your columns definition; use rowSelection instead.',\r\n      )\r\n    }\r\n  })\r\n}\r\n","import { isIndexColumn } from '@core/types/indexColumn'\r\nimport { isSelectionColumn } from '@core/types/selectionColumn'\r\nimport { isBuiltInCellEditor } from '@core/types/cellEditor'\r\n\r\n/** 单元格编辑器呈现模式：overlay 进入编辑态；inline 常驻格内 */\r\nexport type CellEditorMode = 'overlay' | 'inline'\r\n\r\n/** 缺省 overlay，与 Phase 3 行为一致 */\r\nexport const DEFAULT_CELL_EDITOR_MODE: CellEditorMode = 'overlay'\r\n\r\n/** 解析列级 cellEditorMode；缺省 overlay */\r\nexport function resolveCellEditorMode(mode?: CellEditorMode): CellEditorMode {\r\n  if (mode === 'inline') {\r\n    return 'inline'\r\n  }\r\n  return DEFAULT_CELL_EDITOR_MODE\r\n}\r\n\r\n/** 系统列强制 overlay；用户列解析 cellEditorMode */\r\nexport function resolveColumnCellEditorMode(\r\n  colId: string,\r\n  mode?: CellEditorMode,\r\n): CellEditorMode {\r\n  if (isIndexColumn(colId) || isSelectionColumn(colId)) {\r\n    return DEFAULT_CELL_EDITOR_MODE\r\n  }\r\n  return resolveCellEditorMode(mode)\r\n}\r\n\r\n/** 是否为 inline 常驻编辑器列（须配置 cellEditor；系统列恒 false） */\r\nexport function isInlineEditorColumn(column: {\r\n  colId: string\r\n  cellEditorMode?: CellEditorMode\r\n  cellEditor?: unknown\r\n}): boolean {\r\n  if (isIndexColumn(column.colId) || isSelectionColumn(column.colId)) {\r\n    return false\r\n  }\r\n\r\n  if (resolveCellEditorMode(column.cellEditorMode) !== 'inline') {\r\n    return false\r\n  }\r\n\r\n  return column.cellEditor != null\r\n}\r\n\r\n/** 开发模式：inline 误配告警 */\r\nexport function warnIfInlineEditorMisconfigured(\r\n  colId: string,\r\n  options: {\r\n    cellEditorMode?: CellEditorMode\r\n    cellEditor?: unknown\r\n  },\r\n): void {\r\n  if (!import.meta.env.DEV) {\r\n    return\r\n  }\r\n\r\n  const isSystem = isIndexColumn(colId) || isSelectionColumn(colId)\r\n\r\n  if (isSystem && options.cellEditorMode === 'inline') {\r\n    console.warn(\r\n      `[magic-grid] Column \"${colId}\" is a system column and cannot use cellEditorMode: 'inline'. ` +\r\n        'Inline editors apply to user data columns only.',\r\n    )\r\n    return\r\n  }\r\n\r\n  if (options.cellEditorMode === 'inline' && options.cellEditor == null) {\r\n    console.warn(\r\n      `[magic-grid] Column \"${colId}\" has cellEditorMode: 'inline' but no cellEditor. ` +\r\n        'Configure cellEditor (e.g. \"checkbox\") or remove inline mode.',\r\n    )\r\n  }\r\n}\r\n\r\nconst INLINE_NATIVE_EDITORS = new Set(['text', 'number', 'checkbox', 'switch'])\r\n\r\n/** 开发模式：inline 列使用可能依赖 overlay/teleport 的编辑器时告警 */\r\nexport function warnIfInlineOverlayEditor(\r\n  colId: string,\r\n  options: {\r\n    cellEditorMode?: CellEditorMode\r\n    cellEditor?: unknown\r\n  },\r\n): void {\r\n  if (!import.meta.env.DEV || options.cellEditorMode !== 'inline') {\r\n    return\r\n  }\r\n\r\n  const editor = options.cellEditor\r\n  if (editor == null) {\r\n    return\r\n  }\r\n\r\n  if (typeof editor === 'function') {\r\n    console.warn(\r\n      `[magic-grid] Column \"${colId}\" uses cellEditorMode: 'inline' with a custom editor function. ` +\r\n        'Inline editors must not use overlay/teleport; prefer checkbox, switch, text, or number.',\r\n    )\r\n    return\r\n  }\r\n\r\n  if (typeof editor === 'string' && !INLINE_NATIVE_EDITORS.has(editor) && !isBuiltInCellEditor(editor)) {\r\n    console.warn(\r\n      `[magic-grid] Column \"${colId}\" uses cellEditorMode: 'inline' with editor \"${editor}\" ` +\r\n        'which may require an overlay surface. Prefer \"checkbox\", \"switch\", \"text\", or \"number\" for inline columns.',\r\n    )\r\n  }\r\n}\r\n","/**\n * Cell Editor Cache — 类型与纯函数（Phase 42 / M35）\n *\n * 职责：Grid/列 opt-in 开关解析、存储键规则、是否向 overlay 列注入 API。\n * 可变状态与 LRU 在 {@link CellEditorCacheService}（`cellEditorCacheService.ts`）。\n *\n * 存储键：`${rowPart}::${colId}::${resolvedKey}`\n * - rowPart：业务 rowId 字符串；transient 行为 `\\0${internalRowId}`\n * - resolvedKey：消费方 key + 可选列级 namespace 前缀\n */\nimport type { BusinessRowId } from '@core/types/businessRowId'\nimport type { CellEditorMode } from '@core/types/cellEditorMode'\nimport { isInlineEditorColumn } from '@core/types/cellEditorMode'\n\n/** 消费方未传 key 且列无 string namespace 时的默认 slot */\nexport const DEFAULT_CELL_EDITOR_CACHE_KEY = 'default'\n\n/** 列级 flag：`true` 启用 · `string` 固定 namespace · `false` 全局开启时 opt-out */\nexport type CellEditorCacheColumnFlag = boolean | string\n\n/** Grid 级配置（MagicGrid `enableCellEditorCache` / `cellEditorCacheMaxEntries`） */\nexport interface CellEditorCacheGridOptions {\n  /**\n   * 为所有 overlay 列注入 get/set/clear API。\n   * 默认 false（零开销）；列级 `cellEditorCache: false` 可显式 opt-out。\n   */\n  enableCellEditorCache?: boolean\n\n  /**\n   * 会话 cache 最大 **cell bucket** 数 `(rowId,colId)`；超出 LRU 淘汰。\n   * 默认不限。\n   */\n  cellEditorCacheMaxEntries?: number\n}\n\nexport interface ResolvedCellEditorCacheGridOptions {\n  enableCellEditorCache: boolean\n  cellEditorCacheMaxEntries: number | undefined\n}\n\nexport function resolveCellEditorCacheGridOptions(\n  options: CellEditorCacheGridOptions = {},\n): ResolvedCellEditorCacheGridOptions {\n  const maxEntries = options.cellEditorCacheMaxEntries\n  return {\n    enableCellEditorCache: options.enableCellEditorCache ?? false,\n    cellEditorCacheMaxEntries:\n      maxEntries != null && Number.isFinite(maxEntries) && maxEntries > 0\n        ? Math.floor(maxEntries)\n        : undefined,\n  }\n}\n\n/**\n * 存储键 rowId 段。\n * transient 行业务 id 为 null，须传 internalRowId 以免多行新增互相覆盖。\n */\nexport function buildCellEditorCacheRowPart(\n  rowId: BusinessRowId,\n  internalRowId?: string,\n): string {\n  if (rowId !== null) {\n    return String(rowId)\n  }\n  if (internalRowId) {\n    return `\\0${internalRowId}`\n  }\n  return '\\0transient'\n}\n\n/** 完整 Map 键：`rowPart::colId::key` */\nexport function buildCellEditorCacheStorageKey(\n  rowId: BusinessRowId,\n  colId: string,\n  key: string = DEFAULT_CELL_EDITOR_CACHE_KEY,\n  options?: { internalRowId?: string },\n): string {\n  const rowPart = buildCellEditorCacheRowPart(rowId, options?.internalRowId)\n  return `${rowPart}::${colId}::${key}`\n}\n\n/** LRU 粒度：同一格 `(rowId,colId)` 下所有 namespace key 共用一个 bucket */\nexport function buildCellEditorCacheBucketKey(\n  rowId: BusinessRowId,\n  colId: string,\n  options?: { internalRowId?: string },\n): string {\n  const rowPart = buildCellEditorCacheRowPart(rowId, options?.internalRowId)\n  return `${rowPart}::${colId}`\n}\n\nexport interface ResolveCellEditorCacheKeyOptions {\n  userKey?: string\n  columnCellEditorCache?: CellEditorCacheColumnFlag\n}\n\n/**\n * 消费方 key → 存储层 key。\n * 列级 `cellEditorCache: 'part'` 时：`getCellCache()` → `part`；`getCellCache('options')` → `part::options`。\n */\nexport function resolveCellEditorCacheKey(\n  options: ResolveCellEditorCacheKeyOptions = {},\n): string {\n  const { userKey, columnCellEditorCache } = options\n  const namespace =\n    typeof columnCellEditorCache === 'string' ? columnCellEditorCache : undefined\n\n  if (userKey != null && userKey !== '') {\n    return namespace ? `${namespace}::${userKey}` : userKey\n  }\n\n  if (namespace) {\n    return namespace\n  }\n\n  return DEFAULT_CELL_EDITOR_CACHE_KEY\n}\n\nexport interface ShouldInjectCellEditorCacheApiOptions {\n  enableCellEditorCache: boolean\n  colId: string\n  cellEditorMode?: CellEditorMode\n  cellEditor?: unknown\n  columnCellEditorCache?: CellEditorCacheColumnFlag\n}\n\n/** inline 列、列级 false、或未开启全局开关 → 不注入（CellEditorParams 上无 cache 方法） */\nexport function shouldInjectCellEditorCacheApi(\n  options: ShouldInjectCellEditorCacheApiOptions,\n): boolean {\n  if (\n    isInlineEditorColumn({\n      colId: options.colId,\n      cellEditorMode: options.cellEditorMode,\n      cellEditor: options.cellEditor,\n    })\n  ) {\n    return false\n  }\n\n  if (options.columnCellEditorCache === false) {\n    return false\n  }\n\n  if (\n    options.columnCellEditorCache === true ||\n    typeof options.columnCellEditorCache === 'string'\n  ) {\n    return true\n  }\n\n  return options.enableCellEditorCache\n}\n"],"mappings":"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"}
+{"version":3,"file":"cellEditorCache-DmICiO9q.js","names":[],"sources":["../src/core/types/indexColumn.ts","../src/core/types/rowSelectionOptions.ts","../src/core/types/selectionColumn.ts","../src/core/types/cellEditorMode.ts","../src/core/types/cellEditorCache.ts"],"sourcesContent":["import type { ColumnDef } from '@types'\r\nimport type { GridHorizontalAlign, GridVerticalAlign } from '@core/types/align'\r\n\r\n/** 系统索引列 colId；用户 columns 不得占用 */\r\nexport const INDEX_COLUMN_ID = '__index__'\r\n\r\n/** 索引列最小（默认）宽度 px */\r\nexport const INDEX_COLUMN_MIN_WIDTH = 40\r\n\r\n/** 索引列默认起始序号（1-based 展示 = rowIndex + start） */\r\nexport const DEFAULT_INDEX_COLUMN_START = 1\r\n\r\n/** 索引列配置 */\r\nexport interface IndexColumnOptions {\r\n  /** 表头文案；默认空字符串 */\r\n  label?: string\r\n  /** 列宽 px；默认 40；小于 40 时钳制为 40 */\r\n  width?: number\r\n  /** 起始序号（1-based 展示 = rowIndex + start）；默认 1 */\r\n  start?: number\r\n  /**\r\n   * 辅助定位模式：single / multiple（multiple 支持 Ctrl/Shift/拖拉范围）\r\n   * 默认 multiple（Excel 行号式交互）\r\n   */\r\n  focusMode?: 'single' | 'multiple'\r\n  /**\r\n   * 索引列定位是否单向同步到行选择列（业务选中）；core 默认 false，MagicGrid 组件层默认 true。\r\n   * 仅当 indexColumn.focusMode 与 rowSelection 同为 single 或同为 multiple 时生效。\r\n   * 用户在索引列上操作（点击/拖选/再次点击取消）或 API `setIndexFocus`（`mode: 'default'`）时同步；\r\n   * 点击其他区域清除索引定位、行删除 / rowId 迁移等不同步行选择列。\r\n   */\r\n  syncToSelectionColumn?: boolean\r\n  /** 表头水平对齐；默认 center */\r\n  headerAlign?: GridHorizontalAlign\r\n  /** 表头垂直对齐；默认 center */\r\n  headerValign?: GridVerticalAlign\r\n  /** 表体水平对齐；默认 center */\r\n  align?: GridHorizontalAlign\r\n  /** 表体垂直对齐；默认 center */\r\n  valign?: GridVerticalAlign\r\n  /** footer 水平对齐；默认 center */\r\n  footerAlign?: GridHorizontalAlign\r\n  /** footer 垂直对齐；默认 center */\r\n  footerValign?: GridVerticalAlign\r\n  /**\r\n   * 自定义序号展示；入参为 rowsToDisplay 下标。\r\n   * 缺省：(rowIndex) => String(rowIndex + start)\r\n   */\r\n  index?: (rowIndex: number) => number | string\r\n  /**\r\n   * 在索引列 cell 内显示行拖拽把柄；默认 false。\r\n   * 需配合 Grid `rowDragManaged` 或监听 `rowDragEnd` 自行改序。\r\n   */\r\n  showRowDragHandle?: boolean\r\n  /**\r\n   * 索引列底边可拖拽调整行高；默认 false。\r\n   * 对标 AG Grid Row Numbers `enableRowResizer`。\r\n   */\r\n  enableRowResizer?: boolean\r\n}\r\n\r\n/** Grid 级索引列开关与配置（块 0 类型；块 1+ 消费） */\r\nexport interface IndexColumnGridOptions {\r\n  /** 是否显示最左侧索引列；默认 false */\r\n  showIndexColumn?: boolean\r\n  /** 索引列配置；showIndexColumn=true 时生效 */\r\n  indexColumn?: IndexColumnOptions\r\n}\r\n\r\nexport interface ResolvedIndexColumnOptions {\r\n  label: string\r\n  width: number\r\n  start: number\r\n  focusMode: 'single' | 'multiple'\r\n  syncToSelectionColumn: boolean\r\n  showRowDragHandle: boolean\r\n  enableRowResizer: boolean\r\n  headerAlign: GridHorizontalAlign\r\n  headerValign: GridVerticalAlign\r\n  align: GridHorizontalAlign\r\n  valign: GridVerticalAlign\r\n  footerAlign: GridHorizontalAlign\r\n  footerValign: GridVerticalAlign\r\n  index?: (rowIndex: number) => number | string\r\n}\r\n\r\nexport interface ResolvedIndexColumnGridOptions {\r\n  showIndexColumn: boolean\r\n  indexColumn: ResolvedIndexColumnOptions\r\n}\r\n\r\nexport function resolveIndexColumnWidth(width?: number): number {\r\n  return Math.max(INDEX_COLUMN_MIN_WIDTH, width ?? INDEX_COLUMN_MIN_WIDTH)\r\n}\r\n\r\nexport function resolveIndexColumnOptions(\r\n  options: IndexColumnOptions = {},\r\n): ResolvedIndexColumnOptions {\r\n  return {\r\n    label: options.label ?? '',\r\n    width: resolveIndexColumnWidth(options.width),\r\n    start: options.start ?? DEFAULT_INDEX_COLUMN_START,\r\n    focusMode: options.focusMode === 'single' ? 'single' : 'multiple',\r\n    syncToSelectionColumn: options.syncToSelectionColumn ?? false,\r\n    showRowDragHandle: options.showRowDragHandle ?? false,\r\n    enableRowResizer: options.enableRowResizer ?? false,\r\n    headerAlign: options.headerAlign ?? 'center',\r\n    headerValign: options.headerValign ?? 'center',\r\n    align: options.align ?? 'center',\r\n    valign: options.valign ?? 'center',\r\n    footerAlign: options.footerAlign ?? 'center',\r\n    footerValign: options.footerValign ?? 'center',\r\n    index: options.index,\r\n  }\r\n}\r\n\r\nexport function resolveIndexColumnGridOptions(\r\n  options: IndexColumnGridOptions = {},\r\n): ResolvedIndexColumnGridOptions {\r\n  return {\r\n    showIndexColumn: options.showIndexColumn ?? false,\r\n    indexColumn: resolveIndexColumnOptions(options.indexColumn),\r\n  }\r\n}\r\n\r\nexport function isIndexColumn(colId: string): boolean {\r\n  return colId === INDEX_COLUMN_ID\r\n}\r\n\r\n/** `setIndexFocus` 同步策略：default 跟随 grid 配置；manual 由调用方显式控制 */\r\nexport type SetIndexFocusMode = 'default' | 'manual'\r\n\r\n/** `GridApi.setIndexFocus` 可选参数 */\r\nexport interface SetIndexFocusOptions {\r\n  /**\r\n   * - `default`（默认）：与用户点击索引列一致，按 `indexColumn.syncToSelectionColumn` 决定是否同步\r\n   * - `manual`：由 `syncToSelectionColumn` 显式控制，可覆盖 grid 配置\r\n   */\r\n  mode?: SetIndexFocusMode\r\n  /** `mode: 'manual'` 时生效；省略时视为 `false` */\r\n  syncToSelectionColumn?: boolean\r\n}\r\n\r\nexport function resolveColumnDefColId(column: ColumnDef, index: number): string {\r\n  return column.key ?? column.prop ?? `col_${index}`\r\n}\r\n\r\n/** 开发模式：用户 columns 占用系统索引列 colId 时告警 */\r\nexport function warnIfUserColumnsConflictWithIndexColumn(\r\n  columns: readonly ColumnDef[],\r\n): void {\r\n  if (!import.meta.env.DEV) {\r\n    return\r\n  }\r\n\r\n  columns.forEach((column, index) => {\r\n    const colId = resolveColumnDefColId(column, index)\r\n    if (colId === INDEX_COLUMN_ID || column.key === INDEX_COLUMN_ID) {\r\n      console.warn(\r\n        `[magic-grid] Column \"${INDEX_COLUMN_ID}\" is reserved for the system index column. ` +\r\n          'Remove it from your columns definition or use showIndexColumn instead.',\r\n      )\r\n    }\r\n  })\r\n}\r\n","export type RowSelectionMode = 'single' | 'multiple'\n\n/** 行选择配置（Phase 19 · groupSelectsChildren） */\nexport interface RowSelectionConfig {\n  mode: RowSelectionMode\n  /**\n   * tree 模式下选中父节点是否级联选中子孙。默认 `true`。\n   * 对标 AG Grid rowSelection.groupSelectsChildren。\n   */\n  groupSelectsChildren?: boolean\n}\n\nexport type RowSelectionInput =\n  | RowSelectionMode\n  | false\n  | RowSelectionConfig\n\nexport interface ResolvedRowSelectionOptions {\n  mode: RowSelectionMode | false\n  groupSelectsChildren: boolean\n}\n\nexport function normalizeRowSelectionInput(\n  input: RowSelectionInput | undefined,\n): ResolvedRowSelectionOptions {\n  if (input === false) {\n    return { mode: false, groupSelectsChildren: true }\n  }\n\n  if (input == null) {\n    return { mode: 'single', groupSelectsChildren: true }\n  }\n\n  if (typeof input === 'string') {\n    return {\n      mode: input === 'multiple' ? 'multiple' : 'single',\n      groupSelectsChildren: true,\n    }\n  }\n\n  return {\n    mode: input.mode === 'multiple' ? 'multiple' : 'single',\n    groupSelectsChildren: input.groupSelectsChildren ?? true,\n  }\n}\n\nexport function normalizeRowSelectionMode(\n  resolved: ResolvedRowSelectionOptions,\n): RowSelectionMode | false {\n  return resolved.mode\n}\n","import type { RowSelectionMode } from '@core/selection/selectionService'\r\nimport {\r\n  normalizeRowSelectionInput,\r\n  type RowSelectionInput,\r\n} from '@core/types/rowSelectionOptions'\r\n\r\nimport { resolveColumnDefColId } from './indexColumn'\r\nimport type { GridHorizontalAlign, GridVerticalAlign } from '@core/types/align'\r\nimport type { ColumnDef } from '@types'\r\n\r\n/** 系统行选择列 colId；用户 columns 不得占用 */\r\nexport const SELECTION_COLUMN_ID = '__select__'\r\n\r\n/** 行选择列最小宽度 px */\r\nexport const SELECTION_COLUMN_MIN_WIDTH = 40\r\n\r\n/** 行选择列默认宽度 px */\r\nexport const SELECTION_COLUMN_DEFAULT_WIDTH = 40\r\n\r\n/** 表头全选 checkbox 默认 aria-label */\r\nexport const DEFAULT_SELECTION_SELECT_ALL_LABEL = '全选'\r\n\r\n/** 行选择列配置 */\r\nexport interface SelectionColumnOptions {\r\n  /** 列宽 px；默认 40；小于 40 时钳制为 40 */\r\n  width?: number\r\n  /** 表头全选 checkbox 的 aria-label；默认「全选」 */\r\n  selectAllLabel?: string\r\n  /** 行 checkbox 的 aria-label 工厂 */\r\n  rowLabel?: (rowIndex: number) => string\r\n  /** 表头水平对齐；默认 center */\r\n  headerAlign?: GridHorizontalAlign\r\n  /** 表头垂直对齐；默认 center */\r\n  headerValign?: GridVerticalAlign\r\n  /** 表体水平对齐；默认 center */\r\n  align?: GridHorizontalAlign\r\n  /** 表体垂直对齐；默认 center */\r\n  valign?: GridVerticalAlign\r\n  /** footer 水平对齐；默认 center */\r\n  footerAlign?: GridHorizontalAlign\r\n  /** footer 垂直对齐；默认 center */\r\n  footerValign?: GridVerticalAlign\r\n}\r\n\r\n/** Grid 级行选择列配置（块 0 类型；块 1+ 消费） */\r\nexport interface SelectionColumnGridOptions {\r\n  /** 行选择列配置；rowSelection !== false 时生效 */\r\n  selectionColumn?: SelectionColumnOptions\r\n}\r\n\r\nexport interface ResolvedSelectionColumnOptions {\r\n  width: number\r\n  selectAllLabel: string\r\n  rowLabel?: (rowIndex: number) => string\r\n  headerAlign: GridHorizontalAlign\r\n  headerValign: GridVerticalAlign\r\n  align: GridHorizontalAlign\r\n  valign: GridVerticalAlign\r\n  footerAlign: GridHorizontalAlign\r\n  footerValign: GridVerticalAlign\r\n}\r\n\r\nexport interface ResolvedSelectionColumnGridOptions {\r\n  /** rowSelection !== false */\r\n  enabled: boolean\r\n  /** 行选模式；enabled=false 时为占位 single */\r\n  mode: RowSelectionMode\r\n  selectionColumn: ResolvedSelectionColumnOptions\r\n}\r\n\r\nexport function resolveSelectionColumnWidth(width?: number): number {\r\n  return Math.max(SELECTION_COLUMN_MIN_WIDTH, width ?? SELECTION_COLUMN_DEFAULT_WIDTH)\r\n}\r\n\r\nexport function resolveSelectionColumnOptions(\r\n  options: SelectionColumnOptions = {},\r\n): ResolvedSelectionColumnOptions {\r\n  return {\r\n    width: resolveSelectionColumnWidth(options.width),\r\n    selectAllLabel: options.selectAllLabel ?? DEFAULT_SELECTION_SELECT_ALL_LABEL,\r\n    rowLabel: options.rowLabel,\r\n    headerAlign: options.headerAlign ?? 'center',\r\n    headerValign: options.headerValign ?? 'center',\r\n    align: options.align ?? 'center',\r\n    valign: options.valign ?? 'center',\r\n    footerAlign: options.footerAlign ?? 'center',\r\n    footerValign: options.footerValign ?? 'center',\r\n  }\r\n}\r\n\r\nexport function resolveSelectionColumnGridOptions(\r\n  options: {\r\n    rowSelection?: RowSelectionInput\r\n    selectionColumn?: SelectionColumnOptions\r\n  } = {},\r\n): ResolvedSelectionColumnGridOptions {\r\n  // Grid 直建时缺省 rowSelection 仍不注入行选择列；MagicGrid 默认传 'single'。\r\n  if (options.rowSelection == null) {\r\n    return {\r\n      enabled: false,\r\n      mode: 'single',\r\n      selectionColumn: resolveSelectionColumnOptions(options.selectionColumn),\r\n    }\r\n  }\r\n\r\n  const resolved = normalizeRowSelectionInput(options.rowSelection)\r\n  const enabled = resolved.mode !== false\r\n\r\n  return {\r\n    enabled,\r\n    mode: enabled && resolved.mode !== false ? resolved.mode : 'single',\r\n    selectionColumn: resolveSelectionColumnOptions(options.selectionColumn),\r\n  }\r\n}\r\n\r\nexport function isSelectionColumn(colId: string): boolean {\r\n  return colId === SELECTION_COLUMN_ID\r\n}\r\n\r\n/** 开发模式：用户 columns 占用系统行选择列 colId 时告警 */\r\nexport function warnIfUserColumnsConflictWithSelectionColumn(\r\n  columns: readonly ColumnDef[],\r\n): void {\r\n  if (!import.meta.env.DEV) {\r\n    return\r\n  }\r\n\r\n  columns.forEach((column, index) => {\r\n    const colId = resolveColumnDefColId(column, index)\r\n    if (colId === SELECTION_COLUMN_ID || column.key === SELECTION_COLUMN_ID) {\r\n      console.warn(\r\n        `[magic-grid] Column \"${SELECTION_COLUMN_ID}\" is reserved for the system row selection column. ` +\r\n          'Remove it from your columns definition; use rowSelection instead.',\r\n      )\r\n    }\r\n  })\r\n}\r\n","import { isIndexColumn } from '@core/types/indexColumn'\r\nimport { isSelectionColumn } from '@core/types/selectionColumn'\r\nimport { isBuiltInCellEditor } from '@core/types/cellEditor'\r\n\r\n/** 单元格编辑器呈现模式：overlay 进入编辑态；inline 常驻格内 */\r\nexport type CellEditorMode = 'overlay' | 'inline'\r\n\r\n/** 缺省 overlay，与 Phase 3 行为一致 */\r\nexport const DEFAULT_CELL_EDITOR_MODE: CellEditorMode = 'overlay'\r\n\r\n/** 解析列级 cellEditorMode；缺省 overlay */\r\nexport function resolveCellEditorMode(mode?: CellEditorMode): CellEditorMode {\r\n  if (mode === 'inline') {\r\n    return 'inline'\r\n  }\r\n  return DEFAULT_CELL_EDITOR_MODE\r\n}\r\n\r\n/** 系统列强制 overlay；用户列解析 cellEditorMode */\r\nexport function resolveColumnCellEditorMode(\r\n  colId: string,\r\n  mode?: CellEditorMode,\r\n): CellEditorMode {\r\n  if (isIndexColumn(colId) || isSelectionColumn(colId)) {\r\n    return DEFAULT_CELL_EDITOR_MODE\r\n  }\r\n  return resolveCellEditorMode(mode)\r\n}\r\n\r\n/** 是否为 inline 常驻编辑器列（须配置 cellEditor；系统列恒 false） */\r\nexport function isInlineEditorColumn(column: {\r\n  colId: string\r\n  cellEditorMode?: CellEditorMode\r\n  cellEditor?: unknown\r\n}): boolean {\r\n  if (isIndexColumn(column.colId) || isSelectionColumn(column.colId)) {\r\n    return false\r\n  }\r\n\r\n  if (resolveCellEditorMode(column.cellEditorMode) !== 'inline') {\r\n    return false\r\n  }\r\n\r\n  return column.cellEditor != null\r\n}\r\n\r\n/** 开发模式：inline 误配告警 */\r\nexport function warnIfInlineEditorMisconfigured(\r\n  colId: string,\r\n  options: {\r\n    cellEditorMode?: CellEditorMode\r\n    cellEditor?: unknown\r\n  },\r\n): void {\r\n  if (!import.meta.env.DEV) {\r\n    return\r\n  }\r\n\r\n  const isSystem = isIndexColumn(colId) || isSelectionColumn(colId)\r\n\r\n  if (isSystem && options.cellEditorMode === 'inline') {\r\n    console.warn(\r\n      `[magic-grid] Column \"${colId}\" is a system column and cannot use cellEditorMode: 'inline'. ` +\r\n        'Inline editors apply to user data columns only.',\r\n    )\r\n    return\r\n  }\r\n\r\n  if (options.cellEditorMode === 'inline' && options.cellEditor == null) {\r\n    console.warn(\r\n      `[magic-grid] Column \"${colId}\" has cellEditorMode: 'inline' but no cellEditor. ` +\r\n        'Configure cellEditor (e.g. \"checkbox\") or remove inline mode.',\r\n    )\r\n  }\r\n}\r\n\r\nconst INLINE_NATIVE_EDITORS = new Set(['text', 'number', 'checkbox', 'switch'])\r\n\r\n/** 开发模式：inline 列使用可能依赖 overlay/teleport 的编辑器时告警 */\r\nexport function warnIfInlineOverlayEditor(\r\n  colId: string,\r\n  options: {\r\n    cellEditorMode?: CellEditorMode\r\n    cellEditor?: unknown\r\n  },\r\n): void {\r\n  if (!import.meta.env.DEV || options.cellEditorMode !== 'inline') {\r\n    return\r\n  }\r\n\r\n  const editor = options.cellEditor\r\n  if (editor == null) {\r\n    return\r\n  }\r\n\r\n  if (typeof editor === 'function') {\r\n    console.warn(\r\n      `[magic-grid] Column \"${colId}\" uses cellEditorMode: 'inline' with a custom editor function. ` +\r\n        'Inline editors must not use overlay/teleport; prefer checkbox, switch, text, or number.',\r\n    )\r\n    return\r\n  }\r\n\r\n  if (typeof editor === 'string' && !INLINE_NATIVE_EDITORS.has(editor) && !isBuiltInCellEditor(editor)) {\r\n    console.warn(\r\n      `[magic-grid] Column \"${colId}\" uses cellEditorMode: 'inline' with editor \"${editor}\" ` +\r\n        'which may require an overlay surface. Prefer \"checkbox\", \"switch\", \"text\", or \"number\" for inline columns.',\r\n    )\r\n  }\r\n}\r\n","/**\n * Cell Editor Cache — 类型与纯函数（Phase 42 / M35）\n *\n * 职责：Grid/列 opt-in 开关解析、存储键规则、是否向 overlay 列注入 API。\n * 可变状态与 LRU 在 {@link CellEditorCacheService}（`cellEditorCacheService.ts`）。\n *\n * 存储键：`${rowPart}::${colId}::${resolvedKey}`\n * - rowPart：业务 rowId 字符串；transient 行为 `\\0${internalRowId}`\n * - resolvedKey：消费方 key + 可选列级 namespace 前缀\n */\nimport type { BusinessRowId } from '@core/types/businessRowId'\nimport type { CellEditorMode } from '@core/types/cellEditorMode'\nimport { isInlineEditorColumn } from '@core/types/cellEditorMode'\n\n/** 消费方未传 key 且列无 string namespace 时的默认 slot */\nexport const DEFAULT_CELL_EDITOR_CACHE_KEY = 'default'\n\n/** 列级 flag：`true` 启用 · `string` 固定 namespace · `false` 全局开启时 opt-out */\nexport type CellEditorCacheColumnFlag = boolean | string\n\n/** Grid 级配置（MagicGrid `enableCellEditorCache` / `cellEditorCacheMaxEntries`） */\nexport interface CellEditorCacheGridOptions {\n  /**\n   * 为所有 overlay 列注入 get/set/clear API。\n   * 默认 false（零开销）；列级 `cellEditorCache: false` 可显式 opt-out。\n   */\n  enableCellEditorCache?: boolean\n\n  /**\n   * 会话 cache 最大 **cell bucket** 数 `(rowId,colId)`；超出 LRU 淘汰。\n   * 默认不限。\n   */\n  cellEditorCacheMaxEntries?: number\n}\n\nexport interface ResolvedCellEditorCacheGridOptions {\n  enableCellEditorCache: boolean\n  cellEditorCacheMaxEntries: number | undefined\n}\n\nexport function resolveCellEditorCacheGridOptions(\n  options: CellEditorCacheGridOptions = {},\n): ResolvedCellEditorCacheGridOptions {\n  const maxEntries = options.cellEditorCacheMaxEntries\n  return {\n    enableCellEditorCache: options.enableCellEditorCache ?? false,\n    cellEditorCacheMaxEntries:\n      maxEntries != null && Number.isFinite(maxEntries) && maxEntries > 0\n        ? Math.floor(maxEntries)\n        : undefined,\n  }\n}\n\n/**\n * 存储键 rowId 段。\n * transient 行业务 id 为 null，须传 internalRowId 以免多行新增互相覆盖。\n */\nexport function buildCellEditorCacheRowPart(\n  rowId: BusinessRowId,\n  internalRowId?: string,\n): string {\n  if (rowId !== null) {\n    return String(rowId)\n  }\n  if (internalRowId) {\n    return `\\0${internalRowId}`\n  }\n  return '\\0transient'\n}\n\n/** 完整 Map 键：`rowPart::colId::key` */\nexport function buildCellEditorCacheStorageKey(\n  rowId: BusinessRowId,\n  colId: string,\n  key: string = DEFAULT_CELL_EDITOR_CACHE_KEY,\n  options?: { internalRowId?: string },\n): string {\n  const rowPart = buildCellEditorCacheRowPart(rowId, options?.internalRowId)\n  return `${rowPart}::${colId}::${key}`\n}\n\n/** LRU 粒度：同一格 `(rowId,colId)` 下所有 namespace key 共用一个 bucket */\nexport function buildCellEditorCacheBucketKey(\n  rowId: BusinessRowId,\n  colId: string,\n  options?: { internalRowId?: string },\n): string {\n  const rowPart = buildCellEditorCacheRowPart(rowId, options?.internalRowId)\n  return `${rowPart}::${colId}`\n}\n\nexport interface ResolveCellEditorCacheKeyOptions {\n  userKey?: string\n  columnCellEditorCache?: CellEditorCacheColumnFlag\n}\n\n/**\n * 消费方 key → 存储层 key。\n * 列级 `cellEditorCache: 'part'` 时：`getCellCache()` → `part`；`getCellCache('options')` → `part::options`。\n */\nexport function resolveCellEditorCacheKey(\n  options: ResolveCellEditorCacheKeyOptions = {},\n): string {\n  const { userKey, columnCellEditorCache } = options\n  const namespace =\n    typeof columnCellEditorCache === 'string' ? columnCellEditorCache : undefined\n\n  if (userKey != null && userKey !== '') {\n    return namespace ? `${namespace}::${userKey}` : userKey\n  }\n\n  if (namespace) {\n    return namespace\n  }\n\n  return DEFAULT_CELL_EDITOR_CACHE_KEY\n}\n\nexport interface ShouldInjectCellEditorCacheApiOptions {\n  enableCellEditorCache: boolean\n  colId: string\n  cellEditorMode?: CellEditorMode\n  cellEditor?: unknown\n  columnCellEditorCache?: CellEditorCacheColumnFlag\n}\n\n/** inline 列、列级 false、或未开启全局开关 → 不注入（CellEditorParams 上无 cache 方法） */\nexport function shouldInjectCellEditorCacheApi(\n  options: ShouldInjectCellEditorCacheApiOptions,\n): boolean {\n  if (\n    isInlineEditorColumn({\n      colId: options.colId,\n      cellEditorMode: options.cellEditorMode,\n      cellEditor: options.cellEditor,\n    })\n  ) {\n    return false\n  }\n\n  if (options.columnCellEditorCache === false) {\n    return false\n  }\n\n  if (\n    options.columnCellEditorCache === true ||\n    typeof options.columnCellEditorCache === 'string'\n  ) {\n    return true\n  }\n\n  return options.enableCellEditorCache\n}\n"],"mappings":"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"}