arthub-table 0.2.0-beta.8 → 0.2.1

package/dist/types/core/DataGrid.d.ts

@@ -50,6 +50,7 @@ interface AutofillState {
 }
 interface RowDragState {
     isDragging: boolean;
+    dragStartX: number;
     dragStartY: number;
     draggedRowIndices: number[];
     dropIndicatorType: 'line' | 'overlay' | null;
@@ -104,6 +105,17 @@ interface ColumnContextMenuInfo {
     parentKey?: string;
     clientX: number;
     clientY: number;
+    /**
+     * 表头单元格在屏幕坐标系下的矩形（left/top/width/height）。
+     * 供外部把 popover（如右键菜单→筛选）锚点对齐到"该列表头下方左对齐"。
+     * 对 nested-child 列，矩形为子表头本身；对 fixed 左右冻结列，已按可视屏幕坐标换算。
+     */
+    headerBounds: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
     /** 当前选中的列 colId 集合（用于区分「表头右键菜单」和「选中列右键菜单」） */
     selectedColIds: string[];
     /** 当前选中的列原始 key 集合（colKey），方便业务层直接匹配 */
@@ -268,6 +280,25 @@ export interface DataGridOptions {
         /** NestedGrid 实际渲染的数据数组（行索引与 autofillRange 完全一致） */
         nestedGridData: any[];
     }) => void;
+    /** 嵌套子表内子行拖动排序回调（Alt + 拖拽触发，不跨外层行） */
+    onNestedRowDragReorder?: (params: {
+        parentRowData: any;
+        parentColKey: string;
+        parentRowIndex: number;
+        parentColIndex: number;
+        /** 被拖拽的子行索引（相对 nestedGridData） */
+        fromRowIndex: number;
+        /** 目标插入位置索引（相对 nestedGridData） */
+        toRowIndex: number;
+        /** 插入位置：front 插到目标行之前，tail 插到目标行之后 */
+        position: 'front' | 'tail';
+        /** 被拖拽子行数据 */
+        fromRowData: any;
+        /** 目标参考子行数据 */
+        toRowData: any;
+        /** NestedGrid 实际渲染的数据数组 */
+        nestedGridData: any[];
+    }) => void;
     /** 嵌套子表框选变化回调：选区跨子表或单子表变化时触发 */
     onNestedSelectionChange?: (params: {
         parentColKey: string;
@@ -362,6 +393,13 @@ export interface DataGridOptions {
      * Default: false (preserves existing behavior for backward compatibility).
      */
     disableClickOutside?: boolean;
+    /**
+     * 是否隐藏表头业务图标（TAPD / IOMC / fieldHint / link）。
+     * 对齐 DOM 表格的 hideIcon 能力：用户在 "显示表头图标" 开关关闭时，
+     * 表头区域的四种业务图标均不再绘制，但图标右侧的排序/筛选/设置图标不受影响。
+     * 默认 false（显示图标）。
+     */
+    hideHeaderIcons?: boolean;
     onTreeExpand?: (rowData: RowData, expanded: boolean) => void;
     onCellTextClick?: (rowData: RowData, colId: string) => void;
     onCellTotalNumClick?: (rowData: RowData, colId: string) => void;
@@ -390,6 +428,9 @@ export interface DataGridOptions {
         colId: string;
         colIndex: number;
         colTitle: string;
+        colKey: string;
+        colType?: string;
+        parentKey?: string;
         clientX: number;
         clientY: number;
     }) => void;
@@ -398,8 +439,17 @@ export interface DataGridOptions {
         colId: string;
         colIndex: number;
         colTitle: string;
+        colKey: string;
+        colType?: string;
+        parentKey?: string;
         clientX: number;
         clientY: number;
+        headerBounds: {
+            left: number;
+            top: number;
+            width: number;
+            height: number;
+        };
     }) => void;
     /** 嵌套列设置图标点击回调 */
     onNestedSettingsClick?: (info: {
@@ -500,7 +550,13 @@ export interface DataGridOptions {
             height: number;
         };
     }) => void;
-    /** 折叠所有任务回调 */
+    /** 嵌套表格展开/收起回调：展开全部或收起按钮点击时触发，用于通知业务层更新数据 */
+    onNestedExpandToggle?: (info: {
+        parentRowData: any;
+        parentColKey: string;
+        parentRowIndex: number;
+        expanded: boolean;
+    }) => void;
     onCollapseAll?: () => void;
     /** 展开所有任务回调 */
     onExpandAll?: () => void;
@@ -606,6 +662,20 @@ export interface DataGridOptions {
             height: number;
         };
     }) => void;
+    /** 表头 fieldHint info icon hover 回调：鼠标悬停/离开字段提示图标时触发 */
+    onHeaderFieldHintIconHover?: (info: {
+        show: boolean;
+        colKey: string;
+        colIndex: number;
+        colTitle: string;
+        fieldHint: string;
+        position: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }) => void;
     /** 表体 Link icon 点击回调：点击引用字段单元格的 link icon 时触发 */
     onLinkIconClick?: (info: {
         rowData: Record<string, any>;
@@ -774,6 +844,7 @@ declare class DataGrid {
     onNestedAutofillStart?: DataGridOptions['onNestedAutofillStart'];
     onNestedAutofillDragging?: DataGridOptions['onNestedAutofillDragging'];
     onNestedAutofillEnd?: DataGridOptions['onNestedAutofillEnd'];
+    onNestedRowDragReorder?: DataGridOptions['onNestedRowDragReorder'];
     onNestedSelectionChange?: DataGridOptions['onNestedSelectionChange'];
     onNestedSubHeadClick?: DataGridOptions['onNestedSubHeadClick'];
     onNestedCrossAutofillEnd?: DataGridOptions['onNestedCrossAutofillEnd'];
@@ -795,6 +866,8 @@ declare class DataGrid {
     enableKeyboardShortcuts: boolean;
     /** Whether to disable built-in "click outside to close editing" behavior */
     disableClickOutside: boolean;
+    /** 是否隐藏表头业务图标（TAPD / IOMC / fieldHint / link），对齐 DOM 表格 hideIcon */
+    hideHeaderIcons: boolean;
     /** 非受控模式下的完整数据（包含所有分组的子行） */
     private _fullData;
     /** 双缓冲：离屏 canvas（避免每帧创建，懒初始化 + 复用） */
@@ -946,6 +1019,7 @@ declare class DataGrid {
     private isDirty;
     private lastScrollX;
     private lastScrollY;
+    private _afterRenderListeners;
     private _renderErrorCount;
     private _renderPaused;
     private static readonly MAX_CONSECUTIVE_RENDER_ERRORS;
@@ -966,12 +1040,17 @@ declare class DataGrid {
     private headerTextColorMap;
     private sortOrderMap;
     private sortOrderCount;
+    private moduleSortOrderMap;
+    private moduleSortCountMap;
     private _searchMatchColors;
     hoveredHeaderColId: string | null;
     onHeaderSortClick?: (info: {
         colId: string;
         colIndex: number;
         colTitle: string;
+        colKey: string;
+        colType?: string;
+        parentKey?: string;
         clientX: number;
         clientY: number;
     }) => void;
@@ -979,8 +1058,17 @@ declare class DataGrid {
         colId: string;
         colIndex: number;
         colTitle: string;
+        colKey: string;
+        colType?: string;
+        parentKey?: string;
         clientX: number;
         clientY: number;
+        headerBounds: {
+            left: number;
+            top: number;
+            width: number;
+            height: number;
+        };
     }) => void;
     onNestedSettingsClick?: (info: {
         colId: string;
@@ -1071,6 +1159,19 @@ declare class DataGrid {
             height: number;
         };
     }) => void;
+    onHeaderFieldHintIconHover?: (info: {
+        show: boolean;
+        colKey: string;
+        colIndex: number;
+        colTitle: string;
+        fieldHint: string;
+        position: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }) => void;
     onLinkIconClick?: (info: {
         rowData: Record<string, any>;
         colKey: string;
@@ -1136,6 +1237,10 @@ declare class DataGrid {
      * 获取容器可视区域宽、高，设置canvas容器样式尺寸、画布尺寸
      */
     setLayoutSize(options?: DataGridOptions): void;
+    /**
+     * 获取未被 autoFill 改写的表格原始宽度。
+     */
+    getTableOriginalWidth(): number;
     /**
      * 获取表格左、右冻结列宽，表格实际的宽、高
      */
@@ -1180,6 +1285,8 @@ declare class DataGrid {
     selectCell({ colIndex, rowIndex }: {
         colIndex: number;
         rowIndex: number;
+    }, options?: {
+        skipBoundaryAdjust?: boolean;
     }): void;
     resetCellPosition(): void;
     /**
@@ -1311,12 +1418,52 @@ declare class DataGrid {
      * Called when data changes, interaction state changes, etc.
      */
     markDirty(): void;
+    /**
+     * 注册一次性的"下一帧渲染完成后"回调。
+     * 触发时机：initPaint 的 finally 块（draw 完成或抛异常后）。
+     * 回调执行后队列会被清空；每次调用仅添加一个监听器，监听器执行一次后自动移除。
+     * fail-safe：回调内部抛错只会被捕获并 console.error，不影响后续渲染循环。
+     */
+    onceAfterRender(cb: () => void): void;
+    /**
+     * 计算指定列头在屏幕坐标系下的矩形区域，用于外部将 popover / 弹窗锚点
+     * 对齐到"该列表头单元格下方左对齐"。
+     *
+     * 返回值格式为 DOMRect-like 的 { left, top, width, height }，其中：
+     * - left / top：该列表头左上角相对于视口（viewport）的坐标；
+     * - width / height：该列表头的宽高（对 nested-child 即为子表头本身的尺寸）。
+     *
+     * 兼容 3 种 fixed 场景（left / right / 非冻结）以及水平滚动 scrollX。
+     * 对嵌套子列（colType === 'nested-child'），col.y 已是子表头行的 y，
+     * 因此无需额外处理，直接用 col.y 即可得到子表头自身的矩形。
+     */
+    computeHeaderScreenBounds(col: any): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
     /**
      * Resume the render loop after it was paused due to consecutive render errors.
      * Also resets the error counter. Call this after the root cause has been fixed
      * (e.g. after loadData with corrected data).
      */
     resumeRenderLoop(): void;
+    /**
+     * 清除 Body 层的所有内部缓存（不影响接口数据缓存）。
+     *
+     * 典型场景：displayTaskNum 变化时，需要彻底清除 canvas 表格实例的缓存，
+     * 确保后续 loadData 时不会从旧的 body.data 迁移任何状态（如 _nestedExpanded），
+     * 同时所有 Row/Cell 对象会被重新创建。
+     *
+     * 清除范围：
+     * - body.data（设为空数组，阻止 Body.paint() 迁移旧状态）
+     * - body.rowCache / rowAccessTime（Row 对象缓存池和 LRU 访问时间）
+     * - body.visibleRowIndexes / rows（可见行索引和 Row 对象数组）
+     * - body._nestedDirtyRows / _nestedRenderedRows（嵌套表格渲染追踪）
+     * - body.rowHeights / rowOffsets（行高和偏移量数组）
+     */
+    clearBodyCache(): void;
     drawContainer(): void;
     draw(): void;
     /**
@@ -1626,7 +1773,8 @@ declare class DataGrid {
     /**
      * 将指定单元格滚动到可见区域内（通过 rowId 和 colIndex）
      * @param rowId - 行的唯一标识
-     * @param colIndex - 列索引
+     * @param colIndex - 列索引；传入负数（如 -1）表示仅做垂直滚动、保持水平滚动位置
+     *                  （适用于分组组头等不关联具体列的行定位场景）
      */
     scrollCellIntoViewById(rowId: string | number, colIndex: number): void;
     /**
@@ -1721,6 +1869,13 @@ declare class DataGrid {
      * @returns 高亮色字符串，未设置时返回空字符串
      */
     getColumnHighlightColor(columnKey: string): string;
+    /**
+     * 设置是否隐藏表头业务图标（TAPD / IOMC / fieldHint / link）。
+     * 对齐 DOM 表格的 "显示表头图标" 开关：关闭时四种图标均不绘制，
+     * 但排序/筛选/设置图标不受影响，同时图标 hover 热区（fieldHintIconBounds /
+     * linkIconBounds）也会在下次 draw 时被置空，避免隐藏后仍触发 hover。
+     */
+    setHideHeaderIcons(hide: boolean): void;
     /**
      * 批量设置表头文字颜色（用于新加入字段紫色高亮等场景）
      * @param colors 表头文字颜色映射对象：{ columnKey: color }，color 为空字符串表示清除
@@ -1742,7 +1897,18 @@ declare class DataGrid {
         type: 'asc' | 'desc';
     }>): void;
     /**
-     * 获取指定列的排序状态
+     * 批量设置模块排序状态（各模块独立管理排序，与全局排序互不干扰）
+     * @param moduleOrders 模块排序数组：[{ moduleId: string, orders: [{ meta, type }] }]
+     */
+    setModuleSortOrders(moduleOrders: Array<{
+        moduleId: string;
+        orders: Array<{
+            meta: string;
+            type: 'asc' | 'desc';
+        }>;
+    }>): void;
+    /**
+     * 获取全局排序状态
      * @param convertMeta 列的 convertMeta 标识
      * @returns 排序状态对象，未排序时返回 null
      */
@@ -1751,9 +1917,23 @@ declare class DataGrid {
         index: number;
     } | null;
     /**
-     * 获取当前排序列总数
+     * 获取模块排序状态（嵌套子列使用）
+     * @param moduleId 模块 ID（即父列的 key）
+     * @param convertMeta 列的 convertMeta 标识
+     * @returns 排序状态对象，未排序时返回 null
+     */
+    getModuleSortOrder(moduleId: string, convertMeta: string): {
+        type: 'asc' | 'desc';
+        index: number;
+    } | null;
+    /**
+     * 获取全局排序列总数
      */
     getSortOrderCount(): number;
+    /**
+     * 获取指定模块的排序列总数
+     */
+    getModuleSortOrderCount(moduleId: string): number;
     /**
      * 设置搜索匹配颜色
      */
@@ -1832,6 +2012,23 @@ declare class DataGrid {
      * @returns Row data object (deep copy) or null if not found
      */
     testGetRowData(rowId: string | number): Record<string, any> | null;
+    /**
+     * 获取组头行搜索命中高亮状态（用于 E2E / 单元测试验证）。
+     *
+     * @param rowId - 组头行 id（分组模式下通常是 string，如 "group-project-0"）
+     * @returns { matched, currentHighlight } 或 null（行不存在 / 非组头行）
+     */
+    testGetGroupHeaderSearchMatchState(rowId: string | number): {
+        matched: boolean;
+        currentHighlight: boolean;
+    } | null;
+    /**
+     * 获取组头行搜索命中的"首列左边框" x 坐标（用于 E2E / 单元测试验证多层分组的绘制位置）。
+     *
+     * @param rowId - 组头行 id
+     * @returns x 坐标（canvas 相对坐标）或 null（行不存在 / 非组头行 / 未命中 GroupRow 实例）
+     */
+    testGetSearchHighlightFirstLeftBorderX(rowId: string | number): number | null;
     /**
      * Get current scroll position and scrollbar state.
      * @returns ScrollPosition object
@@ -2026,5 +2223,166 @@ declare class DataGrid {
      * 算法：遍历 _fullData，使用分组栈跟踪折叠状态
      */
     filterVisibleRows(fullData: RowData[]): RowData[];
+    /**
+     * Get interactive areas within a column header.
+     * Returns sort/filter icon, resize handle, and settings icon bounds.
+     */
+    testGetHeaderInteractiveAreas(colIndex: number): {
+        header: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        };
+        sortIcon: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        } | null;
+        filterIcon: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        } | null;
+        resizeHandle: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        };
+        settingsIcon: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        } | null;
+        meta: {
+            colId: string;
+            columnKey: string;
+            colType: string;
+            index: number;
+            sortDisabled: boolean;
+            canDrag: boolean;
+            isNested: boolean;
+        };
+    } | null;
+    /**
+     * Get all interactive (clickable) areas within a specific cell.
+     * Returns canvas-relative coordinates for edit icon, link icon, error icon, etc.
+     */
+    testGetCellInteractiveAreas(rowId: string | number, columnKey: string): {
+        cell: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        };
+        editIcon: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        } | null;
+        linkIcon: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        } | null;
+        errorIcon: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        } | null;
+        reminderTriangle: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        } | null;
+        viewerAreas: Array<{
+            type: string;
+            bounds: {
+                canvasX: number;
+                canvasY: number;
+                width: number;
+                height: number;
+            };
+            value?: any;
+        }>;
+        meta: {
+            viewerType: string;
+            readonly: boolean;
+            isLink: boolean;
+            hasError: boolean;
+            hasReminder: boolean;
+            hasNestedGrid: boolean;
+        };
+    } | null;
+    /**
+     * Get interactive areas within a group row header.
+     */
+    testGetGroupRowAreas(rowId: string): {
+        expandArrow: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        };
+        checkbox: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        } | null;
+        row: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        };
+        meta: {
+            expanded: boolean;
+            groupLevel: number;
+            groupName: string;
+            isLeafGroup: boolean;
+            rowId: string;
+        };
+    } | null;
+    /**
+     * Get all visible group rows.
+     */
+    testGetVisibleGroupRows(): Array<{
+        rowId: string;
+        rowIndex: number;
+        expanded: boolean;
+        groupName: string;
+        groupLevel: number;
+        isLeafGroup: boolean;
+    }>;
+    /**
+     * Get current selection, editing, and checked-row state.
+     */
+    testGetSelectionState(): {
+        range: {
+            startRow: number;
+            startCol: number;
+            endRow: number;
+            endCol: number;
+        } | null;
+        activeCell: {
+            rowIndex: number;
+            colIndex: number;
+        } | null;
+        checkedRowIds: (string | number)[];
+        editor: {
+            show: boolean;
+            rowIndex: number;
+            colIndex: number;
+        } | null;
+    };
 }
 export default DataGrid;

package/dist/types/core/Events.d.ts

@@ -17,7 +17,6 @@ interface EventTasks {
 declare class Events {
     grid: DataGrid;
     el: HTMLCanvasElement;
-    isFirefox: boolean;
     eventTasks: EventTasks;
     constructor(grid: DataGrid, el: HTMLCanvasElement);
     init(): void;

package/dist/types/core/GroupRow.d.ts

@@ -35,6 +35,52 @@ declare class GroupRow extends Context {
      * level 2+: 18px（与 level 1 相同，避免叶子分组过度靠右）
      */
     private getLevelIndent;
+    /**
+     * 获取组头行的搜索命中状态。
+     *
+     * 状态来源：rowDataAdapter.preprocessRow 在 isGroup 行上注入的
+     * `_groupHeaderSearchMatched` 和 `_groupHeaderSearchCurrentHighlight` 字段。
+     *
+     * - Separator 行（isSeparateRow）永远返回 false/false，不承载搜索命中语义；
+     * - 非 isGroupHeader 行也返回 false/false（防御性兜底）；
+     * - currentHighlight = true 时，draw() 会绘制 2px 橙色 inset 边框。
+     */
+    getGroupHeaderSearchMatchState(): {
+        matched: boolean;
+        currentHighlight: boolean;
+    };
+    /**
+     * 获取组头行搜索命中高亮的"首列左边框" x 坐标。
+     *
+     * 方案 1A（顶/底/左三边同步内缩到色条右缘）：按 (maxGroupLevel, groupLevel)
+     * 计算序号列分层色条的宽度 `barWidth`，返回 `this.x + barWidth`，使左边框与
+     * `drawGroupHeader` 中色条右缘的灰色分隔竖线 x 位置完全对齐——色条区域不被
+     * 橙色边框包裹，保留分层层次感。
+     *
+     * barWidth 规则（与 drawGroupHeader 色条绘制逻辑一致）：
+     *   maxGroupLevel=0 (1D) → 无色条，barWidth = 0
+     *   maxGroupLevel=1 (2D)：groupLevel=0 → 0；groupLevel>=1 → l0w (6)
+     *   maxGroupLevel=2 (3D)：groupLevel=0 → 0；groupLevel>=1 → l0w (6)；groupLevel>=2 → l0w+l1w (16)
+     *
+     * @param groupLevel - 当前组头行的层级（0 表示最外层）
+     * @returns 色条右缘的 x 坐标，作为顶/底/左三边的公共起点
+     */
+    getSearchHighlightFirstLeftBorderX(groupLevel: number): number;
+    /**
+     * 绘制组头行搜索命中的 2px 橙色 inset 边框（对齐 DOM 表格 data-search-matched-highlight 行为）。
+     *
+     * 边框组合（方案 1A：顶/底/左三边同步内缩到色条右缘）：
+     * - 顶边 + 底边：从 `firstLeftX`（色条右缘）横跨到可视区域右边界，不覆盖序号列色条区
+     * - 首列左边：贴在 `firstLeftX`，与顶/底边起点对齐，视觉上与 `drawGroupHeader`
+     *   中色条右缘的灰色分隔竖线同列，使第二/第三层组头命中框与分组原有左边界对齐
+     * - 末列右边：仅当表格末列在可视区域内时绘制，位置保持不变（tableRightEdge）
+     *
+     * 色条区域（`this.x` 到 `firstLeftX` 之间）刻意不被橙色边框包裹，继续保留分层层次感。
+     *
+     * 仅当"当前高亮"（currentHighlight = true）时绘制，与 DOM 表格保持一致——
+     * "命中但非当前"状态不渲染边框，避免多条命中之间的视觉噪音。
+     */
+    private drawSearchHighlightBorder;
     /**
      * Draw group header row
      */

package/dist/types/core/ImageManager.d.ts

@@ -21,6 +21,8 @@ declare class ImageManager {
     private filterIconCanvas;
     private settingsIcon;
     private settingsIconCanvas;
+    private infoIcon;
+    private infoIconCanvas;
     private tapdIcon;
     private iomcIcon;
     private warningIcon;
@@ -104,6 +106,14 @@ declare class ImageManager {
      * @returns HTMLCanvasElement or HTMLImageElement or null if not loaded
      */
     getFilterIcon(): HTMLCanvasElement | HTMLImageElement | null;
+    /**
+     * Get a colored version of filter icon (on-demand recolor, no cache).
+     * Used for "filter active" state where icon must show a themed highlight color.
+     * @param color Target fill color
+     * @param size Display size (square)
+     * @returns HTMLCanvasElement with colored icon, or null if source icon not yet loaded
+     */
+    getColoredFilterIcon(color: string, size?: number): HTMLCanvasElement | null;
     /**
      * Load settings icon (for nested column parent headers)
      */
@@ -113,6 +123,17 @@ declare class ImageManager {
      * @returns HTMLCanvasElement or HTMLImageElement or null if not loaded
      */
     getSettingsIcon(): HTMLCanvasElement | HTMLImageElement | null;
+    /** fieldHint info icon color */
+    private static INFO_ICON_COLOR;
+    /**
+     * Load fieldHint info icon and recolor to #767E89 (14px for header business icon slot)
+     */
+    private loadInfoIcon;
+    /**
+     * Get fieldHint info icon (recolored 14px canvas version)
+     * @returns HTMLCanvasElement or HTMLImageElement or null if not loaded
+     */
+    getInfoIcon(): HTMLCanvasElement | HTMLImageElement | null;
     /**
      * Load TAPD sync icon (display only)
      */