arthub-table 0.2.47 → 0.2.48

package/dist/types/adapters/DataGridIntegration.d.ts

@@ -519,6 +519,21 @@ export interface DataGridCallbacks {
         };
         tooltipText: string;
     }) => void;
+    /**
+     * Cell overflow hover 回调：鼠标悬停在被截断的 cell 内容（普通文本 / Tag 标签 / 人员名称等）上时触发。
+     * 与 onViewerIconHover 的区别：position 是被截断"整段内容"的屏幕坐标矩形（不是 16x16 icon）。
+     * 业务侧可基于该 position 渲染 OverflowTooltip 组件做精确定位。
+     */
+    onCellOverflowHover?: (info: {
+        show: boolean;
+        position: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        tooltipText: string;
+    }) => void;
     /** Reminder 蓝色三角点击回调：点击单元格右上角蓝色提醒三角时触发（用于外部 ReminderPopper） */
     onReminderClick?: (info: {
         position: {

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

@@ -636,6 +636,22 @@ export interface DataGridOptions {
         };
         tooltipText: string;
     }) => void;
+    /**
+     * Cell overflow hover 回调：鼠标悬停在被截断的 cell 内容（普通文本 / Tag 标签 / 人员名称等）上时触发。
+     * 与 onViewerIconHover 区别：
+     *   - position 是被截断的"整段内容"的屏幕坐标矩形（不是 16x16 的图标）
+     *   - 适配业务侧 OverflowTooltip 组件做精确定位
+     */
+    onCellOverflowHover?: (info: {
+        show: boolean;
+        position: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        tooltipText: string;
+    }) => void;
     /** Reminder 蓝色三角点击回调：当用户点击单元格右上角蓝色提醒三角时触发 */
     onReminderClick?: (info: {
         position: {
@@ -1226,6 +1242,22 @@ declare class DataGrid {
         colIndex: number;
         tooltipText: string;
     } | null;
+    onCellOverflowHover?: (info: {
+        show: boolean;
+        position: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        tooltipText: string;
+    }) => void;
+    /** 当前是否正在 hover cell overflow 区域（用于避免重复触发） */
+    _cellOverflowHoverState: {
+        rowIndex: number;
+        colIndex: number;
+        tooltipText: string;
+    } | null;
     onReminderClick?: (info: {
         position: {
             x: number;

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

@@ -17,16 +17,39 @@ declare class CpPersonViewer implements CellViewer<CpPersonViewerData> {
     readonly type = "cp-person";
     private imageManager;
     private _sm;
+    /**
+     * 每个 cell 内"被截断的 CP person 名称"几何缓存。
+     * Key: `${rowIndex}-${colIndex}`；不主动清理，依赖 draw 重绘覆盖。
+     * 单例 viewer，无需考虑跨 grid 隔离。
+     */
+    private _personOverflowCache;
     private get avatarColors();
     constructor();
     /**
      * Draw CP person content in the cell
      */
     draw(context: ViewerRenderContext, data: CpPersonViewerData): void;
+    /**
+     * 构造整段 tooltip 文本（所有 CP 用户的 nickName，逗号空格拼接，回退到 id）
+     */
+    private buildAllPersonsTooltipText;
     /**
      * Draw persons list (with background tag style, aligned with PersonViewer showNameBackground mode)
      */
     private drawPersons;
+    /**
+     * 鼠标 hover 时检测当前 cell 是否有被截断 / 折叠的 CP person 需要显示完整文本 tooltip。
+     * 命中任意 tag 矩形或 +N 圆形区域，若 fullText 非空则显示。
+     */
+    getTooltip(context: ViewerRenderContext, _data: CpPersonViewerData, localX: number, localY: number): {
+        text: string;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
     /**
      * Draw person avatar (circle shape, using default avatar image)
      */

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

@@ -9,6 +9,12 @@ import type { CellViewer, ViewerRenderContext, DropdownViewerData } from './type
  */
 declare class DropdownViewer implements CellViewer<DropdownViewerData> {
     readonly type = "select";
+    /**
+     * 多选 tag 几何与"是否截断"缓存（仅 drawMultipleTags 分支写入）。
+     * Key: `${rowIndex}-${colIndex}`；不主动清理，依赖 draw 重绘覆盖。
+     * 单例 viewer，无需考虑跨 grid 隔离。
+     */
+    private _tagOverflowCache;
     /**
      * Draw select content in the cell
      */
@@ -35,6 +41,7 @@ declare class DropdownViewer implements CellViewer<DropdownViewerData> {
     private calculateTagWidth;
     /**
      * Draw a tag/badge
+     * @returns 实际绘制的 tag 宽度和是否被截断
      */
     private drawTag;
     /**
@@ -53,5 +60,20 @@ declare class DropdownViewer implements CellViewer<DropdownViewerData> {
      * Truncate text with ellipsis
      */
     private truncateText;
+    /**
+     * 鼠标 hover 时检测当前 cell 是否有需要显示的 tooltip。
+     * 命中场景：
+     *   - 多选模式（drawMultipleTags）：某个 tag 被截断 或 鼠标位于 "+N" 区域（显示全量 options 列表）
+     *   - 单选模式（drawSingleOption）：option label 被截断
+     */
+    getTooltip(context: ViewerRenderContext, _data: DropdownViewerData, localX: number, localY: number): {
+        text: string;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
 }
 export default DropdownViewer;

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

@@ -1,21 +1,27 @@
 /**
  * ModuleViewer - Module tag rendering viewer
  * Displays module information as colored tags in table cells
- * Supports single and multiple modules with overflow handling
+ * 多 tag 渲染采用与 TextViewer.drawMultiTags 一致的策略：
+ *   - 固定 tag 视觉规格（高度 24、圆角 4、textPadding 8、tagGap 4）
+ *   - 单 tag 宽度上限 = 文本理想宽度（一般情况下）
+ *   - 总宽度超过 cell 时，等比缩小所有 tag；缩到 minTagWidth=40 仍放不下则减少可见 tag 数
+ *   - tag 框完整不被切半，超出框宽的文字使用 ellipsis 截断
+ *   - tag 背景色取自 mod.color
+ *   - hover 任一 tag 且存在"被截断或被隐藏"的 tag → 弹整 cell 所有 module 名
  */
 import type { CellViewer, ViewerRenderContext, ModuleViewerData } from './types';
 declare class ModuleViewer implements CellViewer<ModuleViewerData> {
     readonly type = "module";
     /**
-     * Cache of overflow indicator bounds for click detection
-     * Key format: "rowIndex:colIndex"
-     */
-    private overflowBoundsMap;
-    /**
-     * Cache of all modules for a cell (for overflow click callback)
-     * Key format: "rowIndex:colIndex"
+     * drawColoredTags 时每个 cell 内所有 tag 的几何与"是否截断"信息缓存。
+     * - Key: `${rowIndex}-${colIndex}`
+     * - Value: 数组，对应 drawColoredTags 实际绘制的 tag 序列
+     *
+     * 写入：drawColoredTags 末尾覆盖式写入
+     * 读取：getTooltip 用 localX/localY 命中后查询
+     * 清理策略：依赖 draw 自动刷新（每次重绘同 key 覆盖），不主动清理。
      */
-    private cellModulesMap;
+    private _multiTagOverflowCache;
     /**
      * Normalize value to ModuleInfo array
      * Supports: ModuleInfo[], ModuleInfo, string[], string, null/undefined/empty
@@ -26,26 +32,28 @@ declare class ModuleViewer implements CellViewer<ModuleViewerData> {
      */
     draw(context: ViewerRenderContext, data: ModuleViewerData): void;
     /**
-     * Handle click events — detect clicks on "+N" overflow indicator
-     */
-    onClick(context: ViewerRenderContext, data: ModuleViewerData, localX: number, localY: number): boolean;
-    /**
-     * Draw colored module tags.
+     * 绘制彩色 module tag。
      *
-     * 渲染规则（参考图片型实现）：
-     * - 在单元格水平可绘制范围 [x+CELL_PADDING, x+width-CELL_PADDING] 内做矩形 clip 裁剪
-     * - 标签按顺序逐个绘制，能完整放下的完整画
-     * - 第一个放不下的标签：仍然绘制（背景 + 文字），由 clip 自动裁掉超出的部分；之后停止绘制
-     * - 不再使用 "..." 省略号，也不再展示 "+N" 概览
-     * - 极窄场景（剩余空间 1px 也要画，由 clip 处理截断）
+     * 渲染规则（与 TextViewer.drawMultiTags 一致，颜色取自 mod.color）：
+     *   1. 计算每个 tag 的理想宽度 = textWidth + textPadding * 2
+     *   2. 总理想宽度 ≤ 可用宽度 → 各 tag 用理想宽度（每个 tag 独立宽度）
+     *   3. 总理想宽度 > 可用宽度 → 等比缩小，minTagWidth=40 兜底
+     *   4. 缩到 minTagWidth 仍放不下 → 减少可见 tag 数量
+     *   5. 每个 tag 内部文本超过 (tagWidth - textPadding * 2) → ellipsis
      *
-     * 注意：因为不再有 "+N" 点击区域，overflowBoundsMap 总是清空
+     * 与 +N 模式的差异：不画 "+N"、tag 框永远完整、文字用 ellipsis 截断。
      */
     private drawColoredTags;
     /**
      * Draw plain text mode (comma-separated module names)
+     * showColor=false 时使用，保持原有逻辑不变。
      */
     private drawPlainText;
+    /**
+     * Truncate text with ellipsis if it exceeds max width
+     * 与 TextViewer.truncateText 完全一致
+     */
+    private truncateText;
     /**
      * Draw a rounded rectangle
      */
@@ -54,5 +62,24 @@ declare class ModuleViewer implements CellViewer<ModuleViewerData> {
      * Draw placeholder for empty state
      */
     private drawPlaceholder;
+    /**
+     * 鼠标 hover 时检测当前 cell 是否有"被截断或被隐藏"的 module tag 需要显示完整文本 tooltip。
+     *
+     * 命中规则：
+     *   - 从 _multiTagOverflowCache 命中具体 tag → 若 fullText 非空则返回 { text, bounds }
+     *   - 命中 tag 但 fullText 为空（即没有 overflow）→ 不显示 tooltip
+     *   - 未命中任何 tag → 不显示 tooltip
+     *
+     * 与 TextViewer.getTooltip 的 multiTags 分支完全一致。
+     */
+    getTooltip(context: ViewerRenderContext, _data: ModuleViewerData, localX: number, localY: number): {
+        text: string;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
 }
 export default ModuleViewer;

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

@@ -11,6 +11,12 @@ declare class PersonViewer implements CellViewer<PersonViewerData> {
     readonly type = "person";
     private imageManager;
     private _sm;
+    /**
+     * 每个 cell 内"被截断的 person 名称"几何缓存。
+     * Key: `${rowIndex}-${colIndex}`；不主动清理，依赖 draw 重绘覆盖。
+     * 单例 viewer，无需考虑跨 grid 隔离。
+     */
+    private _personOverflowCache;
     private get avatarColors();
     constructor();
     /**
@@ -27,6 +33,11 @@ declare class PersonViewer implements CellViewer<PersonViewerData> {
      * 对齐 DOM 表格 personViewer.ts 中 getAccountHTML 的逻辑
      */
     private getDisplayName;
+    /**
+     * 生成单元格 tooltip 用的完整人员列表文本。
+     * 永远使用 "chinese_and_english" 格式（英文名 (中文名)），与单元格 nameDisplayType 解耦。
+     */
+    private buildAllPersonsTooltipText;
     /**
      * Draw persons
      */
@@ -39,6 +50,7 @@ declare class PersonViewer implements CellViewer<PersonViewerData> {
     private drawPersonsFlexLayout;
     /**
      * Draw a single person with width constraint
+     * @param outInfo 可选输出参数：填充该 person 的命中区域几何 + 截断后完整文本，供 getTooltip 使用
      * @returns Width of the drawn person item
      */
     private drawPersonWithConstraint;
@@ -70,5 +82,18 @@ declare class PersonViewer implements CellViewer<PersonViewerData> {
      * Draw placeholder for empty state
      */
     private drawPlaceholder;
+    /**
+     * 鼠标 hover 时检测当前 cell 是否有被截断的 person 名称需要显示完整文本 tooltip。
+     * 命中任意 person 卡片矩形（含背景模式 / 普通模式），若 fullText 非空则显示。
+     */
+    getTooltip(context: ViewerRenderContext, _data: PersonViewerData, localX: number, localY: number): {
+        text: string;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
 }
 export default PersonViewer;

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

@@ -9,6 +9,26 @@ import type { CellViewer, ViewerRenderContext, TextViewerData } from './types';
  */
 declare class TextViewer implements CellViewer<TextViewerData> {
     readonly type = "text";
+    /**
+     * drawMultiTags 时每个 cell 内所有 tag 的几何与"是否截断"信息缓存。
+     * - Key: `${rowIndex}-${colIndex}`
+     * - Value: 数组，对应 drawMultiTags 实际绘制的 tag 序列
+     *
+     * 写入：drawMultiTags 末尾覆盖式写入
+     * 读取：getTooltip 用 localX/localY 命中后查询
+     * 清理策略：依赖 draw 自动刷新（每次重绘同 key 覆盖），不主动清理。
+     * 该 viewer 在 ViewerRegistry 中是单例，所以缓存是单例级的，不需考虑跨 grid 隔离。
+     */
+    private _multiTagOverflowCache;
+    /**
+     * 单文本场景（普通 draw 分支）的"上一次绘制时的渲染区域"缓存。
+     * - Key: `${rowIndex}-${colIndex}`
+     * - Value: { x, y, width, height, padding, fontSize }
+     *
+     * 写入：draw() 普通文本分支末尾写入
+     * 读取：getTooltip 调用时按需通过 ctx.measureText 临时判定是否溢出
+     */
+    private _textCellGeometryCache;
     /**
      * Draw text content in the cell
      */
@@ -72,5 +92,22 @@ declare class TextViewer implements CellViewer<TextViewerData> {
      * Canvas 端手动计算标签宽度和位置，实现等价的效果
      */
     private drawMultiTags;
+    /**
+     * 鼠标 hover 时检测当前 cell 是否有"被截断的内容"需要显示完整文本 tooltip。
+     *
+     * 命中规则（按优先级）：
+     *   1) drawMultiTags 分支：从 _multiTagOverflowCache 命中具体标签 → 走新通路（bounds = tag 矩形）
+     *   2) 普通文本分支：使用 ctx.measureText 临时判定是否溢出 → 走新通路（bounds = cell 渲染区域）
+     *   3) 否则返回 null（不显示 tooltip）
+     */
+    getTooltip(context: ViewerRenderContext, data: TextViewerData, localX: number, localY: number): {
+        text: string;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
 }
 export default TextViewer;

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

@@ -23,6 +23,18 @@ declare class TextViewerWithSwitcher implements CellViewer<TextViewerWithSwitche
     private _sm;
     private arrowColoredCanvas;
     private arrowColoredColor;
+    /**
+     * 每个 cell 文本绘制几何缓存（用于 getTooltip 中判定文本溢出 → 新通路 onCellOverflowHover）。
+     * - Key: `${rowIndex}-${colIndex}`
+     * - Value: { textStartX, y, availableWidth, height, fontSize }
+     *   - textStartX / y 是 drawText 调用时的绝对画布坐标（与 cell.x / cell.y 不同）
+     *   - availableWidth 是 drawText 入参，等于 cell 内文字区域的可用宽度
+     *
+     * 写入：draw() 调用 drawText 之后写入
+     * 读取：getTooltip 命中文本区域时按需用 ctx.measureText 临时判定是否溢出
+     * 清理策略：依赖 draw 每次重绘自动覆盖同 key，不主动清理。
+     */
+    private _textGeometryCache;
     constructor();
     /**
      * Preload SVG icons
@@ -189,7 +201,13 @@ declare class TextViewerWithSwitcher implements CellViewer<TextViewerWithSwitche
      */
     getTooltip(context: ViewerRenderContext, data: TextViewerWithSwitcherData, localX: number, _localY: number): {
         text: string;
-        iconCenterX: number;
+        iconCenterX?: number;
+        bounds?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
     } | null;
     /**
      * 计算文字实际渲染宽度（用于精确判定文字区域的点击和光标）

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

@@ -49,6 +49,40 @@ declare class WfStateViewer implements CellViewer<WfStateViewerData> {
      * Tag 模式下的光标判断
      */
     private getInteractiveCursorTagMode;
+    /**
+     * 鼠标 hover 时检测当前 cell 的状态文字是否被 ellipsis 截断，是则显示完整文本 tooltip。
+     *
+     * 命中规则（与 onClick / getInteractiveCursor 命中范围对齐）：
+     *   - 空 displayName / 占位符 → 不显示
+     *   - 角标区域 hover → 不显示（角标本身有透明度变化反馈，无文字相关信息）
+     *   - 鼠标不在文字区域内 → 不显示
+     *   - 文字宽度 ≤ 可用宽度（未截断）→ 不显示
+     *   - 否则返回 { text: displayName, bounds: 文字矩形（相对 cell 左上角）}
+     *
+     * 根据 wfStateStyle 分别走 Icon / Tag 两种模式：
+     *   - Icon 模式：可用宽度 = width - PADDING * 2 - ICON_SIZE - ICON_TEXT_GAP
+     *   - Tag 模式：可用宽度 = actualTagWidth - TAG_PADDING * 2
+     */
+    getTooltip(context: ViewerRenderContext, data: WfStateViewerData, localX: number, localY: number): {
+        text: string;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
+    /**
+     * Icon 模式下的 tooltip 命中检测
+     */
+    private getTooltipIconMode;
+    /**
+     * Tag 模式下的 tooltip 命中检测
+     *
+     * 注意：Tag 模式的命中只要鼠标在色块矩形内即可（与 onClickTagMode / getInteractiveCursorTagMode 保持一致），
+     * 不限制 localX 必须严格在文字内，避免色块右侧留白区域不响应造成的体验割裂。
+     */
+    private getTooltipTagMode;
     /**
      * 从 value 中提取状态类型
      */

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

@@ -21,6 +21,26 @@ declare class WorkflowViewer implements CellViewer<WorkflowViewerData> {
      * 获取交互光标
      */
     getInteractiveCursor(context: ViewerRenderContext, data: WorkflowViewerData, localX: number, localY: number): string | null;
+    /**
+     * 鼠标 hover 时检测当前 cell 的工作流文本是否被 ellipsis 截断，是则显示完整文本 tooltip。
+     *
+     * 命中规则：
+     *   - parseValue 为空（占位符）→ 不显示
+     *   - 鼠标不在文本实际占用矩形内 → 不显示
+     *   - 整段文本宽度 ≤ 可用宽度（未截断）→ 不显示
+     *   - 否则返回 { text: 完整 names.join(', '), bounds: 文本矩形（相对 cell 左上角）}
+     *
+     * bounds 锚定到文本实际占用矩形（而非整个 cell），与 onClick / getInteractiveCursor 的命中范围保持一致。
+     */
+    getTooltip(context: ViewerRenderContext, data: WorkflowViewerData, localX: number, localY: number): {
+        text: string;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
     /**
      * 绘制占位符文本
      */

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

@@ -163,18 +163,36 @@ export interface CellViewer<T extends CellViewerData = CellViewerData> {
      */
     onDragEnd?(context: ViewerRenderContext, data: T, newValue: any, startValue?: any): void;
     /**
-     * Optional: Get tooltip info when mouse hovers over a specific area (e.g., task icon, IOMC icon)
+     * Optional: Get tooltip info when mouse hovers over a specific area (e.g., task icon, IOMC icon, overflowed text)
      * @param context Render context
      * @param data Cell data
      * @param localX Mouse X position relative to cell
      * @param localY Mouse Y position relative to cell
      * @returns Tooltip info object if hovering over a tooltip area, null otherwise.
-     *   - text: the tooltip text to display
-     *   - iconCenterX: the center X position of the icon (relative to cell) for precise popup positioning
+     *
+     * 两种通路 / 两种坐标语义（择一返回，不要同时返回）：
+     *
+     * 1) 旧通路（icon hover）：返回 { text, iconCenterX }
+     *    - iconCenterX：图标中心相对于 cell 左边界的 X 坐标（px）
+     *    - Events.ts 会将其包装为 16x16 的 anchor，触发 `onViewerIconHover`
+     *    - 适用于：TextViewerWithSwitcher 的任务图标 / IOMC 提单图标等"图标级"提示
+     *
+     * 2) 新通路（cell overflow hover）：返回 { text, bounds }
+     *    - bounds：要 hover 的"整段文字"相对于 cell 左上角的矩形（px）
+     *    - Events.ts 会将 cell 屏幕坐标 + bounds 拼成绝对位置，触发 `onCellOverflowHover`
+     *    - 适用于：普通文本被截断、Tag 标签 / 人员名称被裁掉等"内容溢出"提示
+     *
+     * 仅设置 bounds 走新通路；仅设置 iconCenterX 走旧通路；两者都未设置视为非法返回，将被忽略。
      */
     getTooltip?(context: ViewerRenderContext, data: T, localX: number, localY: number): {
         text: string;
-        iconCenterX: number;
+        iconCenterX?: number;
+        bounds?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
     } | null;
     /**
      * Optional: Whether to hide the default edit icon on hover

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arthub-table",
-  "version": "0.2.47",
+  "version": "0.2.48",
   "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",