arthub-table 0.2.23 → 0.2.25-next.0

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

@@ -154,6 +154,13 @@ declare class Body {
      *                       如果为 undefined，则从 this.data 中直接读取（适用于外部已直接修改 data 数组的场景）
      */
     refreshColumnData(colKeys: string[], newDataByKey?: Record<string, any>[]): void;
+    /**
+     * 图片列专用脏检查：提取实际 URL 比较，忽略 string↔object 类型震荡
+     * 和对象引用差异（每次 refreshColumnData 传入新对象但内容相同）。
+     */
+    private _imageValueChanged;
+    /** 从 value 中提取图片 URL 数组 */
+    private _extractImageUrls;
     updateCellData(_colIndex: number): void;
     /**
      * 获取所有选中的行对象（返回Row对象而不是RowData）

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

@@ -143,8 +143,6 @@ interface RowContextMenuInfo {
     _isRowChecked?: boolean;
     /** 当前选中行总数 */
     _selectedRowCount?: number;
-    /** Row 对象内部的 _rowId，和 selectedRowIds 中的 key 格式一致 */
-    _internalRowId?: string;
 }
 export interface DataGridOptions {
     width?: number | string;
@@ -759,6 +757,44 @@ export interface DataGridOptions {
      * will be paused to prevent the browser from freezing.
      */
     onRenderError?: (error: unknown, consecutiveErrorCount: number) => void;
+    /**
+     * 外部 OS 文件拖入 cell 时的 4 个回调（仅响应 dataTransfer.types includes 'Files'）。
+     * - DragEnter / DragOver / DragLeave 仅做选中态/视觉提示；选中已由 DataGrid 内部 selectCell 完成。
+     * - Drop 真正触发上传流程（业务侧 controller 接管：插占位 + 调 graph.addFile / addFileOnNonFileNode）。
+     */
+    onExternalFileDragEnter?: (info: {
+        rowIndex: number;
+        colIndex: number;
+        columnKey: string;
+    }) => void;
+    onExternalFileDragOver?: (info: {
+        rowIndex: number;
+        colIndex: number;
+        columnKey: string;
+    } | null) => void;
+    onExternalFileDragLeave?: (info: {
+        rowIndex: number;
+        colIndex: number;
+        columnKey: string;
+    } | null) => void;
+    onExternalFileDrop?: (info: {
+        rowIndex: number;
+        colIndex: number;
+        columnKey: string;
+        files: File[];
+        e?: DragEvent;
+    }) => void;
+    /**
+     * 外部 OS 文件粘贴（Ctrl/Cmd+V 把剪贴板里的文件追加到当前选中 cell）回调。
+     * 与 onExternalFileDrop 形参对称，但语义为"追加上传"——业务侧不应清掉 cell 现有文件。
+     */
+    onExternalFilePaste?: (info: {
+        rowIndex: number;
+        colIndex: number;
+        columnKey: string;
+        files: File[];
+        e?: ClipboardEvent;
+    }) => void;
 }
 declare class DataGrid {
     target: HTMLCanvasElement;
@@ -804,6 +840,7 @@ declare class DataGrid {
     rowIdMap: Map<string, number>;
     selectedRowIds: Set<string>;
     selectedGroupIds: Set<string>;
+    _groupSelectedRowIds: Map<string, string[]>;
     lastSelectedRowIndex: number;
     /** Footer 行高度（showFooter 为 false 时返回 0） */
     get footerHeight(): number;
@@ -1024,6 +1061,28 @@ declare class DataGrid {
     cellValueTransformer?: import('./viewers/types').CellValueTransformer;
     /** Render error callback (see DataGridOptions.onRenderError) */
     onRenderError?: (error: unknown, consecutiveErrorCount: number) => void;
+    /** 外部 OS 文件拖入 cell 时的 4 个回调（详见 DataGridOptions.onExternalFileDrag*） */
+    onExternalFileDragEnter?: DataGridOptions['onExternalFileDragEnter'];
+    onExternalFileDragOver?: DataGridOptions['onExternalFileDragOver'];
+    onExternalFileDragLeave?: DataGridOptions['onExternalFileDragLeave'];
+    onExternalFileDrop?: DataGridOptions['onExternalFileDrop'];
+    onExternalFilePaste?: DataGridOptions['onExternalFilePaste'];
+    /**
+     * 外部 OS 文件拖拽状态机。
+     * - activeCell：当前 hover 的 image/file cell（已被 selectCell 选中）
+     * - previousFocusCell：拖拽开始前的原 focusCell，用于拖拽离开 / drop 完成后还原选区
+     */
+    externalFileDrag: {
+        activeCell: {
+            rowIndex: number;
+            colIndex: number;
+            columnKey: string;
+        } | null;
+        previousFocusCell: {
+            rowIndex: number;
+            colIndex: number;
+        } | null;
+    };
     nestedDataCompareKeys: string[];
     nestedForceRefreshKeys: string[];
     range: RangeState;
@@ -1053,6 +1112,8 @@ declare class DataGrid {
     private isDirty;
     private lastScrollX;
     private lastScrollY;
+    /** [FLICKER-DEBUG] draw 日志节流时间戳 */
+    _lastDrawLogTime: number;
     private _afterRenderListeners;
     private _renderErrorCount;
     private _renderPaused;
@@ -1601,7 +1662,7 @@ declare class DataGrid {
     isRowCheckedByIndex(rowIndex: number): boolean | undefined;
     /**
      * 获取全量数据（非受控模式下包含折叠隐藏的行）
-     * 用于需要遍历所有行（包括折叠不可见的）的场景
+     * 用于 GroupRow.selectGroupRows 遍历所有子行（包括折叠不可见的）
      */
     getFullData(): RowData[];
     getChangedRows(): RowData[];
@@ -1841,6 +1902,94 @@ declare class DataGrid {
         width: number;
         height: number;
     } | null;
+    /**
+     * 根据 canvas 局部坐标命中可见 cell（外部文件拖拽 hit-test 入口）。
+     *
+     * 复用既有 `Body.rows[].cells[].isInsideHorizontalBodyBoundary` /
+     * `isInsideFixedHorizontalBodyBoundary` / 行级 `isInsideVerticaBodyBoundary`，
+     * 不重写坐标转换公式，保证与 mousedown/mousemove/click 路径完全一致
+     * （遵守 canvas-table-event-management SKILL §"Coordinate Systems"）。
+     *
+     * 嵌套子表（NestedGrid）：当命中的主表 cell 持有 nestedGrid 实例且 NestedGrid
+     * 也实现了 getCellAtPoint 时，递归命中子格子；否则返回主表 cell。
+     * 若嵌套表 hit-test 当前未实现（NestedGrid 没有 getCellAtPoint），fallback
+     * 到主表 cell（保证主表场景永不退化），后续 iter 在 NestedGrid 上补该方法即可。
+     *
+     * @param x canvas 局部 X（不含 dpr 缩放）
+     * @param y canvas 局部 Y
+     * @returns 命中的 cell 信息，或 null
+     */
+    getCellAtPoint(x: number, y: number): {
+        rowIndex: number;
+        colIndex: number;
+        columnKey: string;
+        column: any;
+        cell: any;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
+    /**
+     * 判断列是否接受外部 OS 文件 drop。
+     * 规则（按优先级）：
+     * 1. column.acceptExternalFileDrop === false → 显式禁用，永远 false
+     * 2. column.readonly === true → 禁用
+     * 3. column.acceptExternalFileDrop === true → 显式启用
+     * 4. column.type === 'image' | 'file'（或 viewerType 等价）→ 默认启用
+     * 5. 其它 → false
+     */
+    isColumnAcceptingExternalFileDrop(column: any): boolean;
+    /**
+     * 外部文件拖拽：命中 cell 后的核心状态机。
+     * - 命中 image/file（且 acceptExternalFileDrop 不为 false）：
+     *   1) 首次进入：暂存 previousFocusCell；
+     *   2) 切换 cell：调 selectCell 把高亮迁移；
+     *   3) 同 cell：no-op，避免每帧重复 selectCell。
+     * - 命中非 image/file 列 or 命中失败：调 clearExternalFileDragHover 清状态。
+     */
+    handleExternalFileHit(cellInfo: {
+        rowIndex: number;
+        colIndex: number;
+        columnKey: string;
+        column: any;
+        cell: any;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null): void;
+    /**
+     * 清掉外部文件拖拽的视觉状态：
+     * - 还原拖拽前的 focusCell（若存在），否则 clearMultiSelect 清空选区；
+     * - 触发 onExternalFileDragLeave 回调（带最后一个 active cell 信息）；
+     * - 重置内部 externalFileDrag 状态机。
+     *
+     * 2026-05-25 修复（task=27c2d1ef e2e iter9 后真实使用反馈）：
+     *   drop 之后 cell 形成"从 dragenter cell 一直延展到鼠标当前位置"的 rectangle 框选，
+     *   必须用户再 mousedown 一次才恢复。根因：dragenter 期间调 `selectCell` 把
+     *   `selector.isSelected = true`（L1721 进入"多选 latch"状态），后续 mousemove
+     *   会扩展 selector.xArr/yArr。但 drop 是 native drag 事件，不会触发 mouseup，
+     *   `endMultiSelect()` 永不调用 → `isSelected` 永远 latched 为 true。
+     *   修法：在拖拽视觉清理末尾显式把 `selector.isSelected = false`（等价于一次
+     *   合成的 mouseup），同时 `edgeScroller.stop()` 防止边缘自动滚动状态残留
+     *   （endMultiSelect 也会调）。
+     *
+     * 2026-05-26 修复：drop 命中目标 cell 后，UX 预期是\"被上传的那个 cell 保持选中\"
+     *   而不是回退到拖拽前的 focusCell（直觉上正在动作的对象该有焦点）。
+     *   增加可选参数 `dropTarget`：drop 命中且 callback 调通时，由 Events 层传入
+     *   目标 cell；本方法优先 selectCell(dropTarget)，并跳过 previousFocusCell 还原。
+     *   - dragleave 路径不传 dropTarget → 走原 prev 还原逻辑（保留旧行为）
+     *   - drop 未命中（空白处 / 列不接受）路径 Events 层也不传 dropTarget → 同样还原 prev
+     */
+    clearExternalFileDragHover(dropTarget?: {
+        rowIndex: number;
+        colIndex: number;
+    }): void;
     /**
      * 将指定单元格滚动到可见区域内（同时处理垂直和水平方向）
      * - 垂直方向：确保行在视口内
@@ -2295,6 +2444,12 @@ declare class DataGrid {
      */
     private ensureRowIds;
     syncGroupCheckedState(): void;
+    /**
+     * 受控模式下：计算组头应有的 checked 状态，如果与当前不一致则通过回调通知外部修改。
+     * 逻辑与 syncGroupCheckedState 的计算一致，但不直接修改 data.checked 和 selectedGroupIds，
+     * 而是通过 onGroupCheckboxChange 回调让外部决定是否更新。
+     */
+    private _notifyGroupCheckedChanges;
     /**
      * 折叠所有任务（受控模式下触发 onCollapseAll 回调，由外部操作 tableTaskList 后刷新）
      */

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

@@ -13,6 +13,11 @@ interface EventTasks {
         cancel?: () => void;
     };
     documentMousedown: (e: MouseEvent) => void;
+    externalDragEnter: (e: DragEvent) => void;
+    externalDragOver: (e: DragEvent) => void;
+    externalDragLeave: (e: DragEvent) => void;
+    externalDrop: (e: DragEvent) => void;
+    externalPaste: (e: ClipboardEvent) => void;
 }
 declare class Events {
     grid: DataGrid;

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

@@ -280,6 +280,19 @@ declare class GroupRow extends Context {
      * Handle click on group row
      */
     handleClick(mouseX: number, mouseY: number): boolean;
+    /**
+     * 选中/取消选中该组下的所有子行（包括子分组及其子行）
+     *
+     * 使用全量数据（_fullData）而非 body.data，确保收起的组也能正确选中/取消选中。
+     * 从当前组头在全量数据中的位置开始，往后遍历，直到遇到同级或更高级的分组行为止，
+     * 期间所有的普通数据行都属于该组。
+     * 对可见行通过 Row 对象调用 handleCheck，对不可见行直接操作 selectedRowIds。
+     *
+     * @param groupId - 组头行的 ID
+     * @param checked - 目标选中状态
+     * @returns 变更后该组内所有行的 rowId 数组
+     */
+    private selectGroupRows;
     /**
      * 计算该组下将新增的选中行数（不含已选中的行）
      * 用于 maxSelectedRows 前置校验

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

@@ -16,7 +16,7 @@ declare class Row extends Context {
     rowHeader: RowHeader;
     constructor(grid: DataGrid, rowIndex: number, x: number, y: number, height: number, data: RowData);
     isInVerticalAutofill(mouseX: number, mouseY: number): boolean;
-    handleCheck(checked?: boolean, event?: MouseEvent, silent?: boolean): void;
+    handleCheck(checked?: boolean, event?: MouseEvent): void;
     mouseDown(x: number, y: number): void;
     mouseMove(mouseX: number, mouseY: number): void;
     handleAutofill(x: number, y: number): void;

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

@@ -130,6 +130,13 @@ export interface ColumnConfig {
     showFilterIcon?: boolean;
     /** 筛选命中该列时为 true：筛选图标常驻显示且显示激活色 */
     filterIconActive?: boolean;
+    /**
+     * 是否接受外部 OS 文件 drop（从浏览器外拖文件到本列的 cell）。
+     * - 默认 undefined：由 DataGrid 内部判断 column.type === 'image' | 'file' 决定。
+     * - 显式 false：完全禁用该列的外部 drop（即便列类型是 image/file 也不响应）。
+     * - 显式 true：与 image/file 类型守卫一致，由业务层（columnAdapter）显式开启。
+     */
+    acceptExternalFileDrop?: boolean;
     [key: string]: any;
 }
 export interface SelectorState {

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

@@ -14,4 +14,20 @@ declare function getIcon(type: string): string;
  */
 declare function getIconByFileStatus(fileStatus: string | number | undefined, format?: string): any;
 export type { HeaderConfig };
-export { toLeaf, getMaxRow, calCrossSpan, getIcon, getIconByFileStatus, };
+/**
+ * 在 canvas 中心绘制圆形进度环（背景圆 + 前景弧）。
+ * - 视觉与 AssetMatrix 的 SVG `PercentRing.vue` 1:1 对齐：
+ *   背景灰圆 + 蓝色前景弧，从 -π/2 起顺时针扫过 percent/100 圈。
+ * - 用于 ImageViewer / FileViewer 渲染 uploading 占位的进度反馈，
+ *   严禁用 SVG / DOM 元素叠加（必须画在 canvas 内）。
+ *
+ * @param ctx       canvas 2d context
+ * @param cx, cy    圆心
+ * @param r         半径
+ * @param sw        线宽（背景与前景一致）
+ * @param percent   0-100，超出范围会自动 clamp
+ * @param fg        前景（已上传部分）颜色，默认 '#3F9EFF'
+ * @param bg        背景圆颜色，默认 'rgba(0,0,0,0.25)'
+ */
+declare function drawProgressRing(ctx: CanvasRenderingContext2D, cx: number, cy: number, r: number, sw: number, percent: number, fg?: string, bg?: string): void;
+export { toLeaf, getMaxRow, calCrossSpan, getIcon, getIconByFileStatus, drawProgressRing, };

package/dist/types/core/viewers/ImageViewer.d.ts

@@ -52,6 +52,10 @@ declare class ImageViewer implements CellViewer<ImageViewerData> {
      * 绘制多张图片左对齐并排排列在单元格内
      * 与 DOM multiImageViewer 的 renderImg 行为一致：所有图片都展示
      * 如果所有图片按行高等比缩放后总宽度超出可用宽度，则等分可用宽度
+     *
+     * 当 data.uploadingItems 非空时（外部文件 drop 触发上传），
+     * 占位 slot 排在 url 数组之前（与 FileEditor.unshift 行为对齐），
+     * 每个占位 slot 渲染灰底 + 中央 canvas 进度环。
      */
     private drawMultipleImages;
     /**
@@ -62,6 +66,13 @@ declare class ImageViewer implements CellViewer<ImageViewerData> {
      * 为单张未加载的图片绘制占位
      */
     private drawSinglePlaceholder;
+    /**
+     * 为外部 OS 文件 drop 触发的「上传中」占位 slot 绘制：
+     * - 灰底矩形
+     * - 中央 canvas 进度环（与 FileEditor.PercentRing 视觉对齐：背景灰圆 + 蓝色前景弧）
+     * 不使用 SVG / DOM 元素叠加（用户明确要求 loading 必须画在 canvas 里）。
+     */
+    private drawUploadingPlaceholder;
     /**
      * 绘制交付物角标（右下角圆形图标）
      * 与 DOM .mark-icon iconfont 图标对齐：

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

@@ -307,6 +307,21 @@ export interface ImageViewerData extends CellViewerData {
     onImgMouseIn?: (url: string, virtualAnchor: any) => void;
     /** 鼠标移出图片回调（用于隐藏大图预览） */
     onImgMouseOut?: () => void;
+    /**
+     * 正在上传中的占位项（外部 OS 文件 drop 触发上传时由业务层 unshift 进来）。
+     * - id：业务层生成的占位 id（如 `uploading-${rowId}-${ts}-${idx}`），用于进度回写匹配
+     * - name：可选文件名（用于占位 hover 提示，目前 ImageViewer 不显示）
+     * - previewUrl：可选 URL.createObjectURL 本地预览图（image 列）
+     * - progress：0-100，由 EVENTHUB_TYPE.UpdateFileNodeProgress 回调写回
+     * 渲染规则：在 value 数组前面追加占位 slot（占位灰底 + 居中 canvas 进度环），
+     * 上传完成后业务层从 uploadingItems 移除并在 value 头部插入真实 URL。
+     */
+    uploadingItems?: Array<{
+        id: string;
+        name?: string;
+        previewUrl?: string;
+        progress?: number;
+    }>;
 }
 /**
  * Person/User viewer data
@@ -665,6 +680,16 @@ export interface FileItem {
     status?: number;
     /** 交付物角标标记（如 'ah-icon_finish1' / 'ah-icon_help2'） */
     mark?: string;
+    /**
+     * 是否是外部 OS 文件 drop 触发的上传中占位项。
+     * 为 true 时 viewer 会画占位 + canvas 进度环（不走真实 thumbnail / status 路径）。
+     * 由 FileViewer.draw 在合并 uploadingItems → files 时打上，业务层一般不直接设置。
+     */
+    _uploading?: boolean;
+    /** 上传进度 0-100（仅当 _uploading=true 时有意义） */
+    progress?: number;
+    /** 占位 id，用于外部进度事件回写匹配 */
+    uploadingId?: string;
 }
 /**
  * 文件 Viewer 数据接口
@@ -708,6 +733,19 @@ export interface FileViewerData extends CellViewerData {
         id?: string | number;
         ids?: number[];
     }, data: FileViewerData) => void;
+    /**
+     * 正在上传中的占位项（外部 OS 文件 drop 触发上传时由业务层 unshift 进来）。
+     * 渲染规则：在 value 数组前面追加占位 file 项（占位文件图标 + 文件名 + 居中 canvas 进度环），
+     * 上传完成后业务层从 uploadingItems 移除并把真实数据 push 到 value。
+     * 字段语义与 ImageViewerData.uploadingItems 一致，详见那里说明。
+     */
+    uploadingItems?: Array<{
+        id: string;
+        name?: string;
+        fileFormat?: string;
+        previewUrl?: string;
+        progress?: number;
+    }>;
 }
 /**
  * HyperLink text viewer data (超链接文本)

package/dist/types/testing/TestHooks.d.ts

@@ -673,6 +673,48 @@ export interface TestHooksAPI {
             };
         } | null;
     };
+    /**
+     * 直接驱动 onExternalFileDrop callback，绕过浏览器 native HTML5 DataTransfer。
+     *
+     * 背景：Playwright 的 DataTransfer 对 file payload 历来不稳（`AmE2ETest` 既有
+     * `deliverable-upload-download.spec.ts` L760+ 已经因此改成 `setInputFiles`）。
+     * 这里给 e2e 一条**和真实 drop 完全等价**的入口：与 EventManager.handleExternalFileDrop
+     * 调用同一个 callback，能跑通业务侧 onCanvasExternalFileDrop 的全链路。
+     *
+     * 参数：
+     *   - rowId       : 行的用户 id（与 getRowData 入参一致）
+     *   - columnKey   : 列 key（与 getColumnConfig / getCellLayout 入参一致）
+     *   - files       : 浏览器侧构造的 File[]（spec 用 `new File([bytes], name, {type})`）
+     *
+     * 返回：
+     *   - true        : 命中 row + col 且 onExternalFileDrop callback 已被触发
+     *   - false       : row 或 column 找不到 / callback 未注册（spec 应当判 false=失败）
+     */
+    simulateExternalFileDrop: (rowId: string | number, columnKey: string, files: File[]) => boolean;
+    /**
+     * 与 simulateExternalFileDrop 对称：直接驱动 onExternalFilePaste callback，
+     * 绕过浏览器 native ClipboardEvent。语义为"追加上传"，不清除 cell 现有文件。
+     * 返回 true=callback 已触发，false=row/col 找不到或 callback 未注册。
+     */
+    simulateExternalFilePaste: (rowId: string | number, columnKey: string, files: File[]) => boolean;
+    /**
+     * 读取指定 cell 当前传给 viewer.draw 的 data 对象的浅拷贝（含 uploadingItems）。
+     *
+     * 用于 e2e 断言上传占位是否成功插入 / 进度环渲染数据是否回写到位。
+     * 仅暴露 viewer 渲染相关的几个字段，避免把整个内部对象 dump 到 spec 端。
+     *
+     * 返回：null 表示 row 或 column 找不到 / cell 还没绘制过。
+     */
+    getCellViewerData: (rowId: string | number, columnKey: string) => {
+        value: any;
+        uploadingItems: Array<{
+            id: string;
+            name?: string;
+            previewUrl?: string;
+            progress?: number;
+        }> | undefined;
+        status: any;
+    } | null;
 }
 /**
  * Test info for a single nested grid instance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arthub-table",
-  "version": "0.2.23",
+  "version": "0.2.25-next.0",
   "description": "High-performance canvas-based table/grid component for Vue 3 with TypeScript support, featuring virtual scrolling, cell viewers, grouped rows, and nested grids.",
   "main": "dist/arthub-table.common.js",
   "module": "dist/arthub-table.umd.min.js",