@taocompany/magic-grid 0.7.8 → 0.9.0

package/dist/types/core.d.ts

@@ -14,7 +14,11 @@ export declare interface AddRowPayload {
 
 export declare interface AddRowsOptions {
     rows: AddRowItem[];
-    /** 插入起始下标；省略 = 末尾 */
+    /**
+     * 插入起始下标；省略 = 末尾 append。
+     * 默认 `indexMode: 'source'` — 即 **source 下标**（`getData()` / 分组 collation 归一化后的存储序）。
+     * 分组开启时：全量 refresh 前会按分组键重排 source；无 index 时先 append，再由归一化落入对应组块。
+     */
     index?: number;
     /** 下标基准，默认 'source' */
     indexMode?: RowIndexMode;
@@ -26,6 +30,7 @@ export declare interface AsyncRowMutationAddParams {
     }>;
     index?: number;
     indexMode?: RowIndexMode;
+    /** 可用于监听取消（如 Grid destroy 或新一轮 commit） */
     signal: AbortSignal;
 }
 
@@ -40,14 +45,105 @@ export declare interface AsyncRowMutationAddResultRow {
     data?: RowData;
 }
 
-/** 异步行变更持久化钩子（GridOptions.asyncRowMutation） */
+/**
+ * 异步行变更持久化钩子（GridOptions / MagicGrid `asyncRowMutation`）。
+ *
+ * ## 消费端怎么用
+ *
+ * 配置任意钩子后，对应 API **先 await 钩子成功**，再改本地 source；钩子 `throw RowMutationPersistError` 则本地不变。
+ *
+ * | 钩子 | 触发的 API / 交互 |
+ * |------|-------------------|
+ * | `add` | `addRows` |
+ * | `update` | `updateRows` / `applyTransaction({ update })` |
+ * | `remove` | `removeRows` |
+ * | `move` | `moveRow` / `moveRows` / `moveUp` / `moveDown` / `moveUps` / `moveDowns` / **索引列拖拽**（见下） |
+ *
+ * ## move 与拖拽
+ *
+ * - **编程式 move**（`source: 'api'`）：有 `move` 钩子时 await 后再改序；await 期间索引列 loading。
+ * - **索引列拖拽**：有 `move` 钩子时 mouseup 后 await；索引列白底 + 居中 spinner（与 API move 一致）。
+ * - **updateRows / removeRows**：有对应钩子时 await 期间索引列 loading。
+ * - **索引列 loading 前提**：须 `showIndexColumn: true`（建议 `indexColumn.showRowDragHandle: true` 若需拖拽演示）。
+ * - 无需额外配置 `rowDragCommitMode`（已移除）；是否 async 只看有没有 `move`。
+ *
+ * @example 平铺表 · 拖拽与 API 共用一套持久化
+ * ```ts
+ * asyncRowMutation: {
+ *   move: async ({ rowIds, moves, source, signal }) => {
+ *     await api.reorder({ rowIds, moves, fromDrag: source === 'uiRowDrag' })
+ *   },
+ * }
+ * ```
+ *
+ * @example 树形 · hierarchyChanges 持久化（`moves` 可能为空）
+ * ```ts
+ * import { getRowDragCommitHierarchy, RowMutationPersistError } from '@taocompany/magic-grid/types/core'
+ *
+ * move: async (params) => {
+ *   if (params.hierarchyChanges?.length) {
+ *     const changes = getRowDragCommitHierarchy(params, 'noLevel')
+ *     await api.saveTreeOrder({ changes })
+ *     return
+ *   }
+ *   await api.reorder({ moves: params.moves })
+ * }
+ * ```
+ */
 export declare interface AsyncRowMutationHandlers {
-    /** 新增：await 服务端成功后 apply 本地；reject 则不写入 */
+    /** 新增：成功后 apply 本地；reject 则不写入 */
     add?: (params: AsyncRowMutationAddParams) => Promise<AsyncRowMutationAddResult | void>;
-    /** 更新：await 服务端成功后 apply 本地；reject 则不写入 */
+    /** 更新：成功后 apply 本地；reject 则不写入 */
     update?: (params: AsyncRowMutationUpdateParams) => Promise<void>;
-    /** 删除：await 服务端成功后 apply 本地；reject 则不删除 */
+    /** 删除：成功后 apply 本地；reject 则不删除 */
     remove?: (params: AsyncRowMutationRemoveParams) => Promise<void>;
+    /** 行序移动：见模块顶部的 move / 拖拽说明 */
+    move?: (params: AsyncRowMutationMoveParams) => Promise<void>;
+}
+
+/**
+ * `asyncRowMutation.move` 入参。
+ *
+ * `source` 区分调用来源：
+ * - `'api'`：`moveRow` / `moveRows` / `moveUp` / `moveDown` / `moveUps` / `moveDowns`
+ * - `'uiRowDrag'`：索引列 drag handle（配置了 `move` 时 mouseup 后触发）
+ *
+ * 树形 / 分组场景请同时阅读 `moves` 与 `hierarchyChanges`（见 {@link RowHierarchyChange}）。
+ */
+export declare interface AsyncRowMutationMoveParams {
+    /** 本次移动涉及的全部 rowId（含 leader 与 cascade 子树） */
+    rowIds: readonly string[];
+    /** 拖拽 leader 或 API 指定的主行 */
+    leaderRowId: string;
+    /** leader 在 source 数组的目标下标（API 入参或从 moves 推导） */
+    toIndex: number;
+    indexMode?: RowIndexMode;
+    /**
+     * source 平铺数组下标位移；**不含**树 parent 信息。
+     * 平铺 / 分组同级换序时为主要依据；树形仅改 parent 时可能为空数组。
+     */
+    moves: readonly RowMoveItem[];
+    /** 移动行的 data 快照（持久化时可直接用，无需再 getData） */
+    rows: ReadonlyArray<{
+        rowId: string;
+        data: RowData;
+    }>;
+    source: RowMoveSource;
+    signal: AbortSignal;
+    /** 仅 uiRowDrag：指针落在 display 的插入位（与 toIndex 可能不同） */
+    displayIndex?: number;
+    /**
+     * 仅 uiRowDrag / 树形：parentRowId、siblingIndex 相对变更前发生变化的行。
+     * 持久化树序时优先用 {@link getRowDragCommitHierarchy} 过滤。
+     */
+    hierarchyChanges?: readonly RowHierarchyChange[];
+    /** 仅 uiRowDrag：leader apply 后的父节点；根层 null */
+    parentRowId?: string | null;
+    /** 仅 uiRowDrag：leader 在新父下的同级序号（0-based，≠ 业务字段 order） */
+    siblingIndex?: number;
+    treeLevel?: number;
+    /** 仅 uiRowDrag：drop 意图（子级缩进区 / Alt）；≠ apply 后的 parentRowId */
+    nestUnderRowId?: string | null;
 }
 
 export declare interface AsyncRowMutationRemoveParams {
@@ -1232,17 +1328,20 @@ export declare interface FirstRenderedEvent {
  * @example
  * ```ts
  * gridApi.on('indexFocusChanged', (event) => {
- *   api.moveRows({ rowIds: generateFocusedRowIds(event.focusedRows), toIndex: 0 })
+ *   api.moveRows({
+ *     rowIds: generateFocusedRowIds(event.focusedRows),
+ *     toIndex: 0, // 默认 source 下标；也可用 event.focusedRows[0].sourceIndex
+ *   })
  * })
  * ```
  */
-export declare function generateFocusedRowIds(rows: SelectedRowSnapshot | readonly SelectedRowSnapshot[], options?: RowListOptions): RowId[];
+export declare function generateFocusedRowIds(rows: RowSnapshot | readonly RowSnapshot[], options?: RowListOptions): RowId[];
 
 /** 索引 focus：`generateFocusedRowIds` 入参（与 {@link GenerateSelectedRowIdsOptions} 相同） */
 export declare type GenerateFocusedRowIdsOptions = RowListOptions;
 
 /**
- * 单行快照 → `removeRows` / `moveRows` / `getRowType` 等 API 可用的 id。
+ * 单行快照 → `removeRows` / `moveRows` / `getRowIndex` / `getRowKind` 等 API 可用的 id。
  *
  * - 持久化行 → 业务 `rowId`
  * - 临时行 → `internalRowId`（`__MG_TMP__::*`）
@@ -1250,12 +1349,14 @@ export declare type GenerateFocusedRowIdsOptions = RowListOptions;
  * @example
  * ```ts
  * api.on('indexFocusChanged', (event) => {
- *   const id = generateRowId(event.focusedRows[0])
- *   api.getRowType(id)
+ *   const row = event.focusedRows[0]
+ *   if (!row) return
+ *   // row.rowIndex 即 display 下标；ensureIndexVisible 亦需 display
+ *   api.ensureIndexVisible(row.rowIndex)
  * })
  * ```
  */
-export declare function generateRowId(row: SelectedRowSnapshot): RowId;
+export declare function generateRowId(row: RowSnapshot): RowId;
 
 /**
  * checkbox 选中行 → `removeRows` / `moveRows` 可用的 id 列表。
@@ -1267,7 +1368,7 @@ export declare function generateRowId(row: SelectedRowSnapshot): RowId;
  * })
  * ```
  */
-export declare function generateSelectedRowIds(rows: SelectedRowSnapshot | readonly SelectedRowSnapshot[], options?: RowListOptions): RowId[];
+export declare function generateSelectedRowIds(rows: RowSnapshot | readonly RowSnapshot[], options?: RowListOptions): RowId[];
 
 /** checkbox 选中：`generateSelectedRowIds` 入参 */
 export declare type GenerateSelectedRowIdsOptions = RowListOptions;
@@ -1294,25 +1395,29 @@ export declare interface GetDetailRowDataParams {
 }
 
 /**
- * 从 deferred row drag commit 上下文中提取树形层级变更列表。
+ * 从 `asyncRowMutation.move` 的树形字段中提取待持久化的层级变更。
  *
- * - `default`：返回 `context.hierarchyChanges` 的浅拷贝（含 `treeLevel` 及仅 level 变化的项）。
- * - `noLevel`：仅保留 **parentRowId 或 siblingIndex** 相对变更前发生变化的项，
- *   排除「parent / sibling 均未变、仅 treeLevel 不同」的条目。
+ * 传入 `params` 或任意含 `hierarchyChanges` 的对象即可（通常 `move` 钩子的 `params`）。
  *
- * 对接后端 `parentId` + `order` 持久化时，通常使用 `noLevel`。
+ * - `default`：返回全部 `hierarchyChanges`（含仅 treeLevel 变化的项）。
+ * - `noLevel`：仅 parent / sibling 真正变化的行（对接后端 parentId + order 时推荐）。
  *
  * @example
  * ```ts
- * import { getRowDragCommitHierarchy } from '@taocompany/magic-grid'
+ * import { getRowDragCommitHierarchy, RowMutationPersistError } from '@taocompany/magic-grid/types/core'
  *
- * const toPersist = getRowDragCommitHierarchy(context, 'noLevel')
- * for (const item of toPersist) {
- *   await api.update({ id: item.rowId, parentId: item.parentRowId, order: item.siblingIndex })
+ * asyncRowMutation: {
+ *   move: async (params) => {
+ *     const changes = getRowDragCommitHierarchy(params, 'noLevel')
+ *     if (changes.length === 0 && params.moves.length === 0) return
+ *     await api.saveOrder({ changes, moves: params.moves })
+ *   },
  * }
  * ```
  */
-export declare function getRowDragCommitHierarchy(context: RowDragCommitContext, option?: GetRowDragCommitHierarchyOption): RowHierarchyChange[];
+export declare function getRowDragCommitHierarchy(context: {
+    hierarchyChanges?: readonly RowHierarchyChange[];
+}, option?: GetRowDragCommitHierarchyOption): RowHierarchyChange[];
 
 /** {@link getRowDragCommitHierarchy} 过滤模式 */
 export declare type GetRowDragCommitHierarchyOption = 'default' | 'noLevel';
@@ -1326,15 +1431,31 @@ export declare interface GetRowHeightParams {
     rowIndex: number;
 }
 
+/** `getRowIndex` / `getRowIndexes` 选项；`type` 与 `removeRows({ indexMode })` / `moveRows({ indexMode })` 同语义 */
+export declare interface GetRowIndexOptions {
+    /** @default 'source' */
+    type?: RowIndexMode;
+}
+
+export declare interface GetSiblingRowByIteratorOptions<TData = RowData> {
+    direction: SiblingRowDirection;
+    /** 必填；`next(false)` 时返回当前候选行 */
+    iterator: SiblingRowIterator<TData>;
+}
+
 export declare interface GetSiblingRowsByRowIdOptions<TData = RowData> {
     direction: SiblingRowDirection;
     /**
-     * 最多取几条。默认 `1`。
-     * `-1` = 该方向上全部可见相邻行（仍会被 `iterator` 提前截断）。
+     * 最多收集几条。默认 `1`。
+     * `-1` = 该方向全部可见相邻行（仍会被 iterator 提前终止）。
      */
     length?: number;
-    /** 可选；入参为 {@link SelectedRowSnapshot}；`false` 时停止，当前候选行不计入结果 */
+    /** 可选过滤；省略时所有候选均纳入（仅受 `length` 限制） */
     iterator?: SiblingRowIterator<TData>;
+    /**
+     * `next(false)` 终止时是否纳入终止行。默认 `false`（只返回此前 `next()` 通过的行）。
+     */
+    includeStop?: boolean;
 }
 
 /** Grid 验收阈值 */
@@ -1361,7 +1482,7 @@ export declare interface GridApi extends RowMutationGridApi {
      * 增量事务：add / update / remove。
      *
      * - `update` / `remove` 项可通过 `data[rowKey]` 或字符串 rowId 定位行。
-     * - 与 `addRows` / `removeRows` 共用同一刷新管线；大量连续操作建议包在 `beginUpdate` / `endUpdate` 中。
+     * - 与 `addRows` / `updateRows` / `removeRows` 共用同一刷新管线；大量连续操作建议包在 `beginUpdate` / `endUpdate` 中。
      * - 配置 `asyncRowMutation` 时 await 对应钩子成功后再写入本地。
      *
      * @returns 本次事务影响的 RowNode 快照
@@ -1505,53 +1626,105 @@ export declare interface GridApi extends RowMutationGridApi {
      */
     getRowNode(id: RowId): RowNode | undefined;
     /**
-     * 按行 id 获取相邻可见行的用户数据（`rowsToDisplay` 顺序，导出规则同 {@link getData}）。
+     * 按行 id 获取相邻可见行快照（`rowsToDisplay` 顺序；**不含锚点**）。
+     *
+     * 快照结构同 `getSelectedRows` / `focusedRows`。rowId 规则同 {@link getRowIndex}。
      *
      * | 选项 | 说明 |
      * |------|------|
      * | `direction` | `'prev'` 上一行 · `'next'` 下一行 |
-     * | `length` | 默认 `1`；`-1` 取该方向全部 |
-     * | `iterator` | `({ currentRow, row }) => boolean`；均为 {@link SelectedRowSnapshot}；`false` 时停止且不含当前行 |
+     * | `length` | 默认 `1`；`-1` 取该方向全部（iterator 可提前终止） |
+     * | `iterator` | `({ currentRow, row, next })`；每步须 `next()` 或 `next(false)`，未调用视为终止 |
+     * | `includeStop` | 默认 `false`；`next(false)` 时是否纳入终止行 |
      *
-     * **rowId** 支持业务 id 与内核 id（含临时行 `__MG_TMP__::*`）。锚点不可见时返回 `[]`。
+     * 锚点不可见时返回 `[]`。
      *
      * @example
      * ```ts
      * const [nextRow] = api.getSiblingRowsByRowId(2, { direction: 'next' })
      *
-     * api.getSiblingRowsByRowId(5, { direction: 'prev', length: 3 })
-     *
-     * // 向上取同部门相邻行，遇到其他部门停止（不含该行）
-     * api.getSiblingRowsByRowId(5, {
+     * // 向上收集同部门行（含首个不同部门行）
+     * api.getSiblingRowsByRowId(anchorId, {
      *   direction: 'prev',
      *   length: -1,
-     *   iterator: ({ currentRow, row }) =>
-     *     String(currentRow.data.department) === String(row.data.department),
+     *   includeStop: true,
+     *   iterator: ({ currentRow, row, next }) => {
+     *     if (String(currentRow.data.dept) !== String(row.data.dept)) {
+     *       next(false)
+     *       return
+     *     }
+     *     next()
+     *   },
+     * })
+     * ```
+     */
+    getSiblingRowsByRowId(rowId: RowId, options: GetSiblingRowsByRowIdOptions): RowSnapshot[];
+    /**
+     * 沿 `direction` 遍历相邻行，返回 **`next(false)` 终止时** 的 `currentRow` 快照。
+     *
+     * 与 {@link getSiblingRowsByRowId} 共用 iterator 签名；差异在于终止时**返回**该行而非收集数组。
+     * 每个候选行须调用 `next()` 或 `next(false)`，未调用视为终止。
+     *
+     * | 场景 | 返回值 |
+     * |------|--------|
+     * | 某候选行上 `next(false)` | 该行 `RowSnapshot` |
+     * | 遍历结束仍未终止 | `null` |
+     * | 锚点不可见 | `null` |
+     *
+     * @example
+     * ```ts
+     * const boundary = api.getSiblingRowByIterator(anchorId, {
+     *   direction: 'next',
+     *   iterator: ({ currentRow, row, next }) => {
+     *     if (String(currentRow.data.dept) !== String(row.data.dept)) {
+     *       next(false)
+     *       return
+     *     }
+     *     next()
+     *   },
      * })
      * ```
      */
-    getSiblingRowsByRowId(rowId: RowId, options: GetSiblingRowsByRowIdOptions): RowData[];
+    getSiblingRowByIterator(rowId: RowId, options: GetSiblingRowByIteratorOptions): RowSnapshot | null;
     /**
-     * 解析行的展示类型。
+     * 解析行的展示种类（{@link RowKind}）。
      *
      * | 返回值 | 含义 |
      * |--------|------|
-     * | `'BUSINESS'` | 用户业务数据行（含临时行） |
-     * | `'GROUP_HEADER'` / `'GROUP_FOOTER'` / `'DETAIL'` | 合成展示行 |
+     * | `'BUSINESS'` | 用户业务数据行（含 `__MG_TMP__::*` 临时行） |
+     * | `'GROUP_HEADER'` / `'GROUP_FOOTER'` | 分组合成行 |
+     * | `'DETAIL'` | 主从详情 overlay |
+     * | `null` | 行不存在或当前不可见 |
      *
-     * **rowId** 支持业务 id 与内核 id（含临时行 `__MG_TMP__::*`）。从快照取 id 时用 `generateRowId(row)`。行不存在时返回 `null`。
+     * **rowId**：业务 id 或内核 id；从 {@link RowSnapshot} 取 id 时用 `generateRowId(row)`。
+     * 快照本身**不含** `rowKind`，需调用本 API。
      *
      * @example
      * ```ts
-     * import { generateRowId } from '@taocompany/magic-grid'
+     * import { generateRowId, type RowKind } from '@taocompany/magic-grid'
      *
      * api.on('indexFocusChanged', (event) => {
      *   const row = event.focusedRows[0]
-     *   if (row) api.getRowType(generateRowId(row))
+     *   if (!row) return
+     *   const kind: RowKind | null = api.getRowKind(generateRowId(row))
+     *   if (kind !== 'BUSINESS') return
+     *   // 仅对业务数据行执行业务逻辑
      * })
      * ```
      */
-    getRowType(rowId: RowId): GridRowType | null;
+    getRowKind(rowId: RowId): RowKind | null;
+    /**
+     * 按 rowId 查下标。完整说明（source vs display、与快照字段对齐）见 `src/core/row/getRowIndex.ts`。
+     *
+     * @see getRowIndexes — 批量版
+     */
+    getRowIndex(rowId: RowId, options?: GetRowIndexOptions): number | null;
+    /** 批量 {@link getRowIndex}；返回 `RowIndexMap`（id 原样作 key） */
+    getRowIndexes(rowIds: readonly RowId[], options?: GetRowIndexOptions): RowIndexMap;
+    /** display 下标 → 快照；与 `getRowIndex(id, { type: 'display' })` 互逆。越界 → `null` */
+    getRowByIndex(index: number): RowSnapshot | null;
+    /** 批量 {@link getRowByIndex}；跳过无效下标 */
+    getRowsByIndexes(indexes: readonly number[]): RowSnapshot[];
     /**
      * 读取当前渲染与滚动指标（验收 / 调试用途）。
      *
@@ -1703,10 +1876,13 @@ export declare interface GridApi extends RowMutationGridApi {
     /**
      * 读取当前 checkbox 选中的完整快照。
      *
-     * 含 `internalRowId`（临时行 `__MG_TMP__::*`），删除临时行、展示选中项时推荐使用。
+     * 含 `internalRowId`（临时行 `__MG_TMP__::*`）、`sourceIndex`（source 下标）、
+     * `rowIndex`（display 下标），删除临时行、展示选中项时推荐使用。
      * 配合 {@link generateSelectedRowIds} 可转为 `removeRows({ rowIds })` 入参。
+     *
+     * @see {@link getRowIndex} 下标主文档
      */
-    getSelectedRows(): SelectedRowSnapshot[];
+    getSelectedRows(): RowSnapshot[];
     /**
      * 读取索引列 focus 行 id，可直接传给 `moveRows({ rowIds })`。
      *
@@ -1726,7 +1902,7 @@ export declare interface GridApi extends RowMutationGridApi {
      * 读取索引列 focus 行快照（结构同 {@link getSelectedRows}）。
      *
      * `options.mode` 与 {@link getIndexFocusedRowIds} 相同。每项含
-     * `rowId`、`internalRowId`、`isTransient`、`rowIndex`、`data`。
+     * `rowId`、`internalRowId`、`isTransient`、`sourceIndex`（source 下标）、`rowIndex`（display 下标）、`data`。
      *
      * @example
      * ```ts
@@ -1737,7 +1913,7 @@ export declare interface GridApi extends RowMutationGridApi {
      * api.moveRows({ rowIds: api.getIndexFocusedRowIds(), toIndex: 0 })
      * ```
      */
-    getIndexFocusedRows(options?: RowListOptions): SelectedRowSnapshot[];
+    getIndexFocusedRows(options?: RowListOptions): RowSnapshot[];
     /**
      * 设置索引列辅助定位（`IndexFocusService`），不触发鼠标拖拉。
      *
@@ -1971,9 +2147,6 @@ export declare interface GridReadyEvent {
 /** 圆角：false/0 无圆角；true 跟随 size；number 自定义 px。默认 false */
 export declare type GridRounded = number | boolean;
 
-/** 行类型枚举（全大写） */
-export declare type GridRowType = 'BUSINESS' | 'GROUP_HEADER' | 'GROUP_FOOTER' | 'DETAIL';
-
 /** 表格尺寸 preset（与 CSS `magic-grid--size-*` 对齐） */
 export declare type GridSize = 'mini' | 'small' | 'default' | 'large';
 
@@ -2012,7 +2185,7 @@ export declare interface GroupCellRendererMountContext {
 
 /** 分组单元格渲染入参（auto group 列 / groupCellRenderer） */
 export declare interface GroupCellRendererParams {
-    rowKind: 'groupHeader' | 'groupFooter';
+    rowKind: 'GROUP_HEADER' | 'GROUP_FOOTER';
     groupId: string;
     groupField: string;
     groupKey: string;
@@ -2145,7 +2318,7 @@ export declare interface IndexFocusChangedEvent<TData = RowData> {
     /** 业务 id；临时行 `null` */
     focusedRowIds: BusinessRowId[];
     /** 完整行快照（含 internalRowId；推荐用于展示与 moveRows 入参） */
-    focusedRows: SelectedRowSnapshot<TData>[];
+    focusedRows: RowSnapshot<TData>[];
 }
 
 export declare type InvalidEditValueMode = 'block' | 'revert' | 'keep';
@@ -2368,7 +2541,16 @@ export declare interface MagicGridProps<TData = RowData> {
     invalidEditValueMode?: InvalidEditValueMode;
     /** 行编辑跨字段校验 */
     rowValidator?: RowValidator;
-    /** 异步行 CRUD 持久化钩子 */
+    /**
+     * 异步行 CRUD / 行序持久化钩子。
+     *
+     * - 有 `move`：编程式 move API 与索引列拖拽均 await 成功后再改本地；拖拽 mouseup 前仅视觉预览。
+     * - 无 `move`：拖拽 mouseup 立刻改序（sync）；编程式 move 亦 sync。
+     * - update / remove / move await 期间：受影响行**索引列**显示 loading（须 `showIndexColumn: true`）。
+     * - 失败：`throw RowMutationPersistError(message)`，本地不变。
+     *
+     * @see AsyncRowMutationHandlers · AsyncRowMutationMoveParams（types/core）
+     */
     asyncRowMutation?: AsyncRowMutationHandlers;
     /** 容器高度 */
     height?: string | number;
@@ -2435,15 +2617,6 @@ export declare interface MagicGridProps<TData = RowData> {
      * 对标 AG Grid `rowDragManaged`。
      */
     rowDragManaged?: boolean;
-    /**
-     * managed 模式 commit 策略：`sync`（默认 live move）| `deferred`（mouseup 后 await onRowDragCommit）。
-     */
-    rowDragCommitMode?: RowDragCommitMode;
-    /**
-     * deferred 模式：mouseup 后、apply 前调用；返回 false 则不写 source。
-     * MagicGrid 亦支持 `:on-row-drag-commit` prop（与 Grid option 等价）。
-     */
-    onRowDragCommit?: RowDragCommitHandler;
     /**
      * 行级动态高度（无 DOM）；优先于默认 rowHeight，低于手动 setRowHeight。
      * 对标 AG Grid `getRowHeight`。
@@ -2657,12 +2830,14 @@ export declare interface MagicValidationRule {
 export declare interface MoveRowOptions {
     /** 内部 rowId */
     rowId: string;
-    /** 目标下标 */
+    /** 目标下标（由 indexMode 解释；最终写入 source） */
     toIndex: number;
-    /** 下标基准，默认 `source` */
+    /** 下标基准，默认 `'source'` */
     indexMode?: RowIndexMode;
     /** live drag 中间态为 false；mouseup 收尾为 true（默认 true） */
     finished?: boolean;
+    /** @internal asyncRowMutation.move：plan-only，不写 source、不 emit */
+    deferCommit?: boolean;
 }
 
 /**
@@ -2673,9 +2848,9 @@ export declare interface MoveRowOptions {
 export declare interface MoveRowsGridApiOptions {
     /** 待移动 rowId（保持 source 内相对顺序） */
     rowIds: readonly RowId[];
-    /** 目标下标；`indexMode` 解释（默认针对 leader 行） */
+    /** 目标下标（indexMode 解释；最终写入 source；默认针对 leader 行） */
     toIndex: number;
-    /** 下标基准，默认 `source` */
+    /** 下标基准，默认 `'source'` */
     indexMode?: RowIndexMode;
     /**
      * 块 anchor 行；省略时取 `rowIds` 在 source 中最早出现的行。
@@ -2874,17 +3049,18 @@ export declare interface RowDoubleClickedEvent<TData = RowData> {
 }
 
 /**
- * deferred row drag · 传给 `onRowDragCommit` / `@row-drag-commit` 的上下文。
+ * 内核组装的拖拽 commit 上下文（Grid 内部使用）。
+ *
+ * 消费端在 `asyncRowMutation.move` 中收到的是 {@link AsyncRowMutationMoveParams}，
+ * 树形字段与本文档一致。本类型仍导出，供 `getRowDragCommitHierarchy` 等工具的类型引用。
  *
  * ### 持久化怎么选字段
  *
  * | 场景 | 主用字段 |
  * |------|----------|
  * | 平铺 / 纯同级换序 | `moves` |
- * | 树形改父、上移一级、下移一级、挂到子级 | `hierarchyChanges`（可用 `getRowDragCommitHierarchy(_, 'noLevel')` 排除仅 level 变化） |
- * | leader 落点快捷读 | `parentRowId` / `siblingIndex` / `treeLevel`（与 leader 的 hierarchyChange 一致） |
- *
- * `nestUnderRowId` 为 **drop 意图**（指针落在子级缩进区 / Alt）；`parentRowId` 为 **apply 后结果**。
+ * | 树形改父、上移一级、下移一级、挂到子级 | `hierarchyChanges` |
+ * | leader 落点快捷读 | `parentRowId` / `siblingIndex` / `treeLevel` |
  */
 export declare interface RowDragCommitContext {
     signal: AbortSignal;
@@ -2918,7 +3094,7 @@ export declare interface RowDragCommitContext {
     nestUnderRowId?: string | null;
 }
 
-/** deferred row drag · commit 结束（成功时随后 emit rowMoved + rowDragEnd） */
+/** await 持久化结束；`committed: true` 时随后 emit `rowMoved` + `rowDragEnd` */
 export declare interface RowDragCommitFinishedEvent {
     commitId: number;
     rowId: BusinessRowId;
@@ -2928,17 +3104,7 @@ export declare interface RowDragCommitFinishedEvent {
     reason?: string;
 }
 
-export declare type RowDragCommitHandler = (context: RowDragCommitContext) => Promise<RowDragCommitHandlerResult> | RowDragCommitHandlerResult;
-
-export declare type RowDragCommitHandlerResult = boolean | void | {
-    ok: boolean;
-    reason?: string;
-};
-
-/** managed 行拖拽 commit 策略 */
-export declare type RowDragCommitMode = 'sync' | 'deferred';
-
-/** deferred row drag · commit 开始（公开事件会投影 rowId 为 BusinessRowId） */
+/** 配置了 asyncRowMutation.move 时，拖拽 mouseup 后开始 await 持久化（公开事件会投影 rowId 为 BusinessRowId） */
 export declare interface RowDragCommitStartedEvent {
     rowId: BusinessRowId;
     rowIds: readonly BusinessRowId[];
@@ -3056,7 +3222,7 @@ export declare type RowHeightChangeSource = 'api' | 'uiRowResized' | 'autoHeight
  * 对接后端 `parentId` + `order` 时使用；`siblingIndex` 为 Grid 内部 0-based 同级序，≠ 业务字段 `order`。
  */
 export declare interface RowHierarchyChange {
-    /** 内部 rowId（deferred handler 内为 string；公开事件会投影为 BusinessRowId） */
+    /** 内部 rowId（async move 钩子内为 string；公开事件会投影为 BusinessRowId） */
     rowId: string;
     /** 变更前父节点 rowId；根层为 null */
     previousParentRowId: string | null;
@@ -3094,10 +3260,25 @@ export declare interface RowIdPromotedEvent {
     data: RowData;
 }
 
-/** 行插入/删除下标基准：source = 存储顺序；display = 当前可见顺序（含 sort/filter） */
+/** key = 入参 id；value = 下标或 `null` */
+export declare type RowIndexMap = Partial<Record<RowId, number | null>>;
+
+/** 行插入/删除下标基准：source = 存储顺序；display = 当前可见顺序（含 sort/filter）。详见 `src/core/row/getRowIndex.ts` */
 export declare type RowIndexMode = 'source' | 'display';
 
-export declare type RowKind = 'data' | 'detail' | 'groupHeader' | 'groupFooter';
+/**
+ * 行的展示种类（Grid 全表统一枚举，与 `GridApi.getRowKind` 返回值一致）。
+ *
+ * | 值 | 含义 |
+ * |----|------|
+ * | `'BUSINESS'` | 用户业务数据行（含临时行）；`RowNode.rowKind` 缺省时视同此项 |
+ * | `'GROUP_HEADER'` | 分组标题（display 合成行） |
+ * | `'GROUP_FOOTER'` | 分组小计（display 合成行） |
+ * | `'DETAIL'` | 主从展开的详情 overlay |
+ *
+ * 类型导出：`import type { RowKind } from '@taocompany/magic-grid'`
+ */
+export declare type RowKind = 'BUSINESS' | 'GROUP_HEADER' | 'GROUP_FOOTER' | 'DETAIL';
 
 /** 行列表过滤模式（选中 / focus 共用） */
 export declare type RowListMode = 'all' | 'business' | 'temp';
@@ -3107,6 +3288,15 @@ export declare interface RowListOptions {
     mode?: RowListMode;
 }
 
+/** async defer commit 计划（内核用）；`RowMoveResult.commitPlan` 在 GridApi 返回前通常已剥离 */
+export declare interface RowMoveCommitPlan {
+    rows: RowNode[];
+    moves: readonly RowMoveItem[];
+    source: RowMoveSource;
+    finished: boolean;
+    treeDisplayInsertIndex?: number;
+}
+
 /** rowMoved 事件 */
 export declare interface RowMovedEvent {
     rowId: BusinessRowId;
@@ -3143,6 +3333,8 @@ export declare interface RowMoveResult {
     toIndex?: number;
     reason?: string;
     moves?: readonly RowMoveItem[];
+    /** plan-only（deferCommit）时携带，供 async 持久化后 commit；GridApi 返回前通常已剥离 */
+    commitPlan?: RowMoveCommitPlan;
 }
 
 export declare type RowMoveSource = 'api' | 'uiRowDrag';
@@ -3161,8 +3353,11 @@ export declare interface RowMutationGridApi {
      * - 省略 `data[rowKey]` 或值为 `null` 时生成**临时行**（`RowNode.id = __MG_TMP__::*`）；
      *   `getData()` 导出时对应字段为 `null`。
      * - 带有效 `rowKey` 的新增行视为持久化行，须保证主键唯一。
+     * - `index` / `indexMode` 语义同 {@link getRowIndex}（默认 source）；最终写入 source 存储。
      * - 配置 `asyncRowMutation.add` 时 await 服务端成功后再写入本地。
      *
+     * @see {@link getRowIndex} 下标主文档（source / display · `sourceIndex` / `rowIndex`）
+     *
      * @returns 本次变更涉及的 RowNode 快照（add / remove / update）
      */
     addRows(options: AddRowsOptions): Promise<RowNodeTransaction>;
@@ -3170,13 +3365,25 @@ export declare interface RowMutationGridApi {
      * 按 rowId 和/或行下标删除行。
      *
      * - `rowIds`：内核 id 或业务主键值（number / string 均可）。
-     * - `indexes`：配合 `indexMode` 使用 `'source'`（存储顺序）或 `'display'`（排序/filter 后可见顺序）。
+     * - `indexes`：配合 `indexMode`（默认 `'source'`）；语义同 {@link getRowIndex}。
      * - 删除正在编辑的行会先取消编辑；选区 / 索引定位 / 校验反馈会同步清理。
      * - 配置 `asyncRowMutation.remove` 时 await 服务端成功后再删除本地。
+     * - await 期间受影响行索引列 loading（须 `showIndexColumn: true`）。
      *
      * @returns 本次删除的 RowNode 快照
      */
     removeRows(options: RemoveRowsOptions): Promise<RowNodeTransaction>;
+    /**
+     * 按 rowKey 批量更新行字段。
+     *
+     * - 每项 `data` 须含 `rowKey` 以定位持久化行；字段与现有 `row.data` 合并（Object.assign）。
+     * - 等价于 `applyTransaction({ update })`，语义更贴近 {@link addRows} / {@link removeRows}。
+     * - 配置 `asyncRowMutation.update` 时 await 服务端成功后再写入本地。
+     * - await 期间受影响行索引列 loading（须 `showIndexColumn: true`）。
+     *
+     * @returns 本次更新的 RowNode 快照
+     */
+    updateRows(options: UpdateRowsOptions): Promise<RowNodeTransaction>;
     /**
      * 删除当前 checkbox 选中的行。
      *
@@ -3184,6 +3391,7 @@ export declare interface RowMutationGridApi {
      * - 等价于 `removeRows({ rowIds: generateSelectedRowIds(getSelectedRows()) })`，但更简洁。
      * - `scope: 'all'`（默认）含离屏选中；`'current'` 仅当前 display 可见选中。
      * - 配置 `asyncRowMutation.remove` 时 await 服务端成功后再删除本地。
+     * - await 期间受影响行索引列 loading（须 `showIndexColumn: true`）。
      */
     removeSelectedRows(options?: ClearRowSelectionOptions): Promise<RowNodeTransaction>;
     /**
@@ -3206,23 +3414,79 @@ export declare interface RowMutationGridApi {
      */
     promoteRowId(options: PromoteRowIdOptions): PromoteRowIdResult;
     /**
-     * 编程式移动行（Phase 15）。
+     * 编程式移动行。始终改写 **source** 存储顺序；`indexMode` 仅解释 `toIndex` 入参。
+     *
+     * **sort 或 filter（含 quick filter）激活时**：与 {@link moveRows}、{@link moveUp}、managed 拖拽一样 **全部拒绝**。
      *
-     * - `indexMode: 'source'`（默认）按 source 存储顺序移动。
-     * - `indexMode: 'display'` 按当前 display 顺序移动；sort 激活时拒绝。
-     * - managed UI drag 成功时 emit `rowMoved`（`source: 'uiRowDrag'`）；API 调用为 `'api'`。
+     * - 配置 `asyncRowMutation.move` 时 await 服务端成功后再改本地行序。
+     * - await 期间受影响行索引列 loading（须 `showIndexColumn: true`）。
+     *
+     * @see docs/43-move-rows-api.md
+     * @see src/core/row/getRowIndex.ts — source / display 下标说明
      */
-    moveRow(rowId: RowId, toIndex: number, indexMode?: RowIndexMode): RowMoveResult;
+    moveRow(rowId: RowId, toIndex: number, indexMode?: RowIndexMode): Promise<RowMoveResult>;
     /**
      * 编程式批量移动行（保持 source 内相对顺序）。
      *
+     * **sort 或 filter 激活时**全部拒绝（见 {@link moveRow}）。
+     *
      * - `rowIds.length === 1` 时等价于 {@link moveRow}。
      * - `leaderRowId` 省略时取 `rowIds` 在 source 中最早出现的行。
-     * - 成功时为块内每一行 emit `rowMoved`（`source: 'api'`）。
+     * - 配置 `asyncRowMutation.move` 时 await 服务端成功后再改本地行序。
+     * - await 期间受影响行索引列 loading（须 `showIndexColumn: true`）。
      *
      * @see docs/43-move-rows-api.md
      */
-    moveRows(options: MoveRowsGridApiOptions): RowMoveResult;
+    moveRows(options: MoveRowsGridApiOptions): Promise<RowMoveResult>;
+    /**
+     * 在存储顺序中将行上移一位。
+     *
+     * | 表形态 | 步进范围 | 内部坐标 |
+     * |--------|----------|----------|
+     * | 平铺表 | 全局 source 邻居 | `indexMode: 'source'` |
+     * | 分组表 | 同 `leafGroupPathKey` 组内 leaf | `indexMode: 'source'`（collation 归一化后的子序列） |
+     * | 树形表 | 同父兄弟 | `indexMode: 'display'`（可见兄弟邻居） |
+     *
+     * **rowId**：业务 id 或内核 id（含 `__MG_TMP__::*` 临时行）。
+     *
+     * sort 或 filter 激活时与 {@link moveRow} 相同，全部拒绝。
+     *
+     * - 配置 `asyncRowMutation.move` 时 await 服务端成功后再改本地行序。
+     * - await 期间受影响行索引列 loading（须 `showIndexColumn: true`）。
+     *
+     * @returns 移动后的行快照；行不存在、已在边界或 sort/filter 激活时 `null`
+     */
+    moveUp(rowId: RowId): Promise< RowSnapshot | null>;
+    /**
+     * 在存储顺序中将行下移一位（语义同 {@link moveUp}）。
+     */
+    moveDown(rowId: RowId): Promise< RowSnapshot | null>;
+    /**
+     * 批量步进上移（保持块内相对顺序）。
+     *
+     * - `rowIds` 接受业务 id 或内核 id（含 `__MG_TMP__::*` 临时行）。
+     * - `rowIds.length === 1` 时语义同 {@link moveUp}，返回单元素数组或 `[]`。
+     * - sort 或 filter 激活时与 {@link moveUp} 相同，全部拒绝并返回 `[]`。
+     * - 配置 `asyncRowMutation.move` 时 await 服务端成功后再改本地行序（内部走 {@link moveRows}）。
+     * - await 期间受影响行索引列 loading（须 `showIndexColumn: true`）。
+     *
+     * @returns 移动后的行快照（source 序）；行不存在、已在边界或 sort/filter 激活时 `[]`
+     */
+    moveUps(rowIds: readonly RowId[]): Promise< RowSnapshot[]>;
+    /**
+     * 批量步进下移（语义同 {@link moveUps}）。
+     * 配置 `asyncRowMutation.move` 时同样 await 持久化后再 apply；await 期间索引列 loading（须 `showIndexColumn: true`）。
+     */
+    moveDowns(rowIds: readonly RowId[]): Promise< RowSnapshot[]>;
+}
+
+/**
+ * 异步持久化失败时在 move/add/update/remove 钩子中 throw。
+ * Grid 不会 apply 本地变更；拖拽场景还会 emit `rowDragCommitFinished(committed: false)`。
+ */
+export declare class RowMutationPersistError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
 }
 
 export declare interface RowMutationRemovedSnapshot {
@@ -3235,9 +3499,10 @@ export declare interface RowMutationRowSnapshot {
     /**
      * 当前 `RowNode.id`。
      * 持久化行等于 `String(data[rowKey])`；临时行为 `__MG_TMP__::*`（**不是**业务 null）。
-     * 与 {@link SelectedRowSnapshot.rowId}（业务投影）语义不同，请注意区分。
+     * 与 {@link RowSnapshot.rowId}（业务投影）语义不同，请注意区分。
      */
     rowId: BusinessRowId;
+    /** source 下标（与 {@link RowSnapshot.sourceIndex} 同语义，事件专用字段名） */
     rowIndex: number;
     data: RowData;
     isTransient: boolean;
@@ -3257,9 +3522,11 @@ export declare interface RowNode {
     rowHeight: number;
     /** 行高是否为估算值（v1 固定行高时为 false） */
     estimated: boolean;
-    /** 在 rowsToDisplay 中的下标 */
+    /** display 下标：在 rowsToDisplay 中的位置（positionRows 写入；sort/filter 后会变） */
     rowIndex: number;
-    /** Phase 17 · 行种类；缺省 `data` */
+    /** source 下标：在 sourceRows 中的存储位置（syncSourceRowIndexes 写入；move/add/remove 后会变） */
+    sourceIndex: number;
+    /** 行种类；缺省 `'BUSINESS'`。公开查询请用 `GridApi.getRowKind` */
     rowKind?: RowKind;
     /** Phase 17 · detail 行：指向主行 id */
     masterRowId?: string;
@@ -3338,6 +3605,30 @@ export declare type RowSelectionInput = RowSelectionMode | false | RowSelectionC
 
 export declare type RowSelectionMode = 'single' | 'multiple';
 
+/**
+ * 行快照——`getSelectedRows` / `getIndexFocusedRows` /
+ * `selectionChanged.selectedRows` / `indexFocusChanged.focusedRows` 共用。
+ */
+export declare interface RowSnapshot<TData = RowData> {
+    /** 业务主键；临时行恒 `null` */
+    rowId: BusinessRowId;
+    /** 内核 rowId；临时行为 `__MG_TMP__::*` */
+    internalRowId: string;
+    isTransient: boolean;
+    /**
+     * 行在 **source 数据**中的下标（`RowNode.sourceIndex`）。
+     * 与 `api.getRowIndex(id)`（默认 `type: 'source'`）一致；非 source 行恒 `-1`。
+     */
+    sourceIndex: number;
+    /**
+     * 行在 **rowsToDisplay** 中的下标（`RowNode.rowIndex`）。
+     * 与 `api.getRowIndex(id, { type: 'display' })` 一致。
+     */
+    rowIndex: number;
+    /** 与 `api.getData()` 导出规则一致 */
+    data: TData;
+}
+
 /** 纵向合并行数（≥1）；缺省视为 1；仅表体 */
 export declare type RowSpanFn = (params: CellSpanParams) => number;
 
@@ -3449,21 +3740,6 @@ export declare interface SelectableParams {
     isTransient: boolean;
 }
 
-/**
- * 行快照——`getSelectedRows` / `getIndexFocusedRows` /
- * `selectionChanged.selectedRows` / `indexFocusChanged.focusedRows` 共用。
- */
-export declare interface SelectedRowSnapshot<TData = RowData> {
-    /** 业务主键；临时行恒 `null` */
-    rowId: BusinessRowId;
-    /** 内核 rowId；临时行为 `__MG_TMP__::*` */
-    internalRowId: string;
-    isTransient: boolean;
-    rowIndex: number;
-    /** 与 `api.getData()` 导出规则一致 */
-    data: TData;
-}
-
 /**
  * 行选择列 checkbox 选中集变化时触发。MagicGrid：`@selection-changed`。
  *
@@ -3481,7 +3757,7 @@ export declare interface SelectionChangedEvent<TData = RowData> {
     /** 当前选中的业务 row id（临时行为 null；不可单独用于删除临时行） */
     selectedRowIds: BusinessRowId[];
     /** 当前选中的完整行快照（含 internalRowId；推荐用于删除与展示） */
-    selectedRows: SelectedRowSnapshot<TData>[];
+    selectedRows: RowSnapshot<TData>[];
 }
 
 /** 行选择列配置 */
@@ -3540,23 +3816,29 @@ export declare interface SetRowHeightChange {
     height: number;
 }
 
-/** 相邻方向：按当前可见列表 `rowsToDisplay` 的上一行 / 下一行 */
+/** 相邻方向：相对锚点在 `rowsToDisplay` 中的上一行 / 下一行 */
 export declare type SiblingRowDirection = 'prev' | 'next';
 
-/**
- * 逐条过滤候选相邻行。
- * 返回 `false` 时立即停止，且**不包含** `currentRow`。
- */
-export declare type SiblingRowIterator<TData = RowData> = (params: SiblingRowIteratorParams<TData>) => boolean;
+/** 逐条过滤候选相邻行；须在每步调用 `next()` 或 `next(false)` */
+export declare type SiblingRowIterator<TData = RowData> = (params: SiblingRowIteratorParams<TData>) => void;
 
-/** `iterator` 回调入参（与 `getSelectedRows` / `focusedRows` 快照结构一致） */
+/** iterator 回调入参；快照结构与 `getSelectedRows` / `focusedRows` 一致 */
 export declare interface SiblingRowIteratorParams<TData = RowData> {
     /** 当前正在考察的候选相邻行 */
-    currentRow: SelectedRowSnapshot<TData>;
-    /** 锚点行（即调用时传入的 `rowId` 对应行） */
-    row: SelectedRowSnapshot<TData>;
+    currentRow: RowSnapshot<TData>;
+    /** 锚点行（调用 API 时传入的 `rowId` 对应行，全程不变） */
+    row: RowSnapshot<TData>;
+    /** 步进控制；每个候选行必须调用一次 */
+    next: SiblingRowNext;
 }
 
+/**
+ * iterator 步进控制。
+ * - `next()` 或 `next(true)`：接受当前候选行
+ * - `next(false)`：在此行终止
+ */
+export declare type SiblingRowNext = (continueIteration?: boolean) => void;
+
 export declare interface SizeColumnsToContentColumnLimit {
     colId: string;
     minWidth?: number;
@@ -3800,6 +4082,18 @@ export declare interface UpdateRowDimensionsParams {
     rowHeightMax?: number;
 }
 
+export declare interface UpdateRowItem {
+    /**
+     * 要合并的字段；须含 `rowKey` 以定位持久化行。
+     * 临时行可省略 rowKey，由 apply 层按 data 引用匹配（与 applyTransaction 一致）。
+     */
+    data: RowData;
+}
+
+export declare interface UpdateRowsOptions {
+    rows: UpdateRowItem[];
+}
+
 export declare interface ValidateCellsOptions {
     /** 待校验的单元格列表 */
     cells: GridCellPosition[];