arthub-table 0.2.6 → 0.2.7-next.1

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

@@ -790,6 +790,7 @@ declare class DataGrid {
     edgeScroller: EdgeScroller;
     rowIdMap: Map<string, number>;
     selectedRowIds: Set<string>;
+    _groupSelectedRowIds: Map<string, string[]>;
     lastSelectedRowIndex: number;
     /** Footer 行高度（showFooter 为 false 时返回 0） */
     get footerHeight(): number;
@@ -2459,6 +2460,10 @@ declare class DataGrid {
      *   - 任务名是否真的存在于 body.data / _fullData 但被规则筛掉了（broadScan 命中数）
      *   - 前 3 行的字段集合是什么样（用于人工核对 task name 落在哪个字段）
      *
+     * task=b1464bc3/iter#4 增强：返回新增 `columnsSummary`——top-level 列的
+     * `{index, key, name, fixed, hasChildren}` 摘要（最多 50 条），用于 freeze-column
+     * spec 在 `waitForFieldFrozenState` 超时时精准区分"controller 未生效"vs"grid 未刷新"。
+     *
      * 返回结构刻意保持小（前 3 行 sample, 字段名列表）—— 便于 console.log 整段直接 dump。
      *
      * @param name - 可选；提供时会做一次 case-insensitive includes 扫描，返回命中数和首批样本
@@ -2482,6 +2487,13 @@ declare class DataGrid {
                 rowKeyValue: any;
             }>;
         } | null;
+        columnsSummary: Array<{
+            index: number;
+            key: string;
+            name: string;
+            fixed: string;
+            hasChildren: boolean;
+        }>;
     };
     /**
      * Look up a column's business `key` by header text / column title.
@@ -2553,6 +2565,41 @@ declare class DataGrid {
         groupLevel: number;
         isLeafGroup: boolean;
     }>;
+    /**
+     * 列出当前可见的所有 ⊕ AddTaskRow 行的 canvas 几何（task=be29ce06）。
+     *
+     * 仅返回 `body.rows` 中 `instanceof AddTaskRow` 的行——AddTaskRow 是数据驱动
+     * 的特殊 canvas 行（`Body.ts` L905 `if (isAddTaskRow(rowData)) new AddTaskRow(...)`），
+     * 不走 cell renderer 路径，所以 `testGetAllVisibleCells` 不会返回它的 cell。
+     * 这里专门给 e2e 暴露 ⊕ 圆心的精确 canvas 坐标，规避 spec 端按
+     * `originFixedWidth/2` 估算在分组下偏到行号区。
+     *
+     * 几何**严格复刻** `AddTaskRow.isInsideIconArea` 的 `bw + iconX + hitPadding=4`
+     * 计算（一字不差）：保证"e2e 鼠标命中点 = AddTaskRow 运行时判定命中点"。
+     *
+     * 返回的 `iconArea` 已经包含 hitPadding：spec 用 `(canvasX + width/2,
+     * canvasY + height/2)` → `canvasToViewport` → `page.mouse.click` 即可命中。
+     *
+     * 这是 LRN-20260512-001 约定的"长期稳定 e2e 锚点 API"，不要随手隐藏。
+     */
+    testGetAddTaskRowAreas(): Array<{
+        rowId: string;
+        rowIndex: number;
+        groupId: string | number | null;
+        parentGroupLevel: number | null;
+        rowArea: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        };
+        iconArea: {
+            canvasX: number;
+            canvasY: number;
+            width: number;
+            height: number;
+        };
+    }>;
     /**
      * Get current selection, editing, and checked-row state.
      */

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

@@ -32,7 +32,7 @@ export interface RichTextViewerData extends CellViewerData {
     placeholder?: string;
 }
 /**
- * 解析富文本值，去除 HTML 标签
+ * 解析富文本值，去除 HTML 标签 + 解码常见 HTML 实体。
  * <img> 标签替换为 [图片]，<video> 标签替换为 [视频]
  */
 export declare function getDisplayValue(value: string | null | undefined): string;

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

@@ -351,6 +351,21 @@ export interface TestHooksAPI {
      * Get all visible group rows with their expand/collapse state.
      */
     getVisibleGroupRows: () => VisibleGroupRowInfo[];
+    /**
+     * 列出当前可见的所有 ⊕ AddTaskRow 行的 canvas 几何（task=be29ce06）。
+     *
+     * 仅返回当前 `body.rows` 中 `instanceof AddTaskRow` 的行——即虚拟滚动已经
+     * 实例化的 AddTaskRow（hit-test 必须基于已实例化的行：`isInsideIconArea`
+     * 依赖 `row.y` / `row.height` / `data._parentGroupLevel`）。
+     *
+     * 调用前 spec 应先确保表格已滚动到目标 ⊕ 行所在视口；本 hook 不做隐式 scroll
+     * （spec 用 `scrollToRow` 或 wheel 自己定位）。
+     *
+     * 这是 LRN-20260512-001 约定的"长期稳定 e2e 锚点 API"——业务侧 / 表格侧
+     * 重构时不要随手隐藏。详见 CONTROLLER_API_CONTRACT.md `getAddTaskRowAreas`
+     * 段。
+     */
+    getAddTaskRowAreas: () => AddTaskRowArea[];
     /**
      * Get current selection, editing, and checked-row state.
      */
@@ -472,6 +487,110 @@ export interface TestHooksAPI {
                 rowKeyValue: any;
             }>;
         } | null;
+        /**
+         * task=b1464bc3/iter#4：freeze-column 诊断专用——top-level columns 的 fixed
+         * 状态摘要。spec 在 canvas 模式调 `__AM_E2E__.controller.freezeColumns(...)`
+         * 后会轮询 `grid.columns[i].fixed`，本字段让 spec / verify 在轮询超时时
+         * 一次性 dump "key/name/fixed/hasChildren"，精准区分"controller 没改"
+         * vs "grid 还没把 fixed 广播出去"两种根因。最多 50 条，避免大表 console 爆掉。
+         */
+        columnsSummary: Array<{
+            index: number;
+            key: string;
+            name: string;
+            fixed: string;
+            hasChildren: boolean;
+        }>;
+    };
+    /**
+     * task=f479647b/iter#1：freeze-column 长期卡死专用诊断探针。
+     *
+     * 背景：spec `freeze-column.spec.ts` 在 canvas 分支调
+     * `freezeFieldsViaController(page, [target])`，candidate 列表里依次尝试
+     * `freezeColumns / setFreezeColumns / freezeColumn / toggleFreezeColumn`，
+     * 全部 fail 后吐 `controller.toggleFreezeColumn is not a function`——历史 4 轮
+     * 都凭这条错误信息推断"AssetMatrix 没暴露 API"，但实际业务侧（FillerInitController）
+     * 已经 public 暴露 freezeColumn(s) / unfreezeColumn(s) / toggleFreezeColumn / setFreezeColumns
+     * 等多个方法。所以问题不在"业务有没有实现"，而是 spec 端拿到的
+     * `__AM_E2E__.controller` **运行时形状**与预期不符（candidate name 全找不到）。
+     *
+     * 这个探针不动业务逻辑，仅做"实地探查"——把 spec 失败现场需要看到的事实
+     * 一次性 dump 出来：
+     *
+     *   - `available`: window.__AM_E2E__.controller 是否真的挂上了
+     *   - `constructorName`: ctrl.constructor.name（运行时类名，区分 mainPanel
+     *      controller vs 子表 dialog controller vs perspectiveTable）
+     *   - `propsName`: ctrl.props?.name（确认是不是 "mainPanel"）
+     *   - `prototypeChain`: 原型链每一层的 constructor.name（ts-mixer 拼出来的
+     *      Mixin 链，让我们能看到 FillerInitController / FillerDataGridController
+     *      / Disposable 等具体到哪层挂的方法）
+     *   - `freezeMethodsByLevel`: 原型链每一层 own keys 中匹配 /freeze/i 的并集
+     *      （包含父类被 ts-mixer 拷贝过来的方法名 vs 真实定义所在的层）
+     *   - `typeofChecks`: spec 实际调的 candidate name 对应的 typeof 结果，让我们
+     *      一眼看到"freezeColumns 是 function 吗""toggleFreezeColumn 是 undefined 吗"
+     *   - `byNameKeys`: __AM_E2E__.byName 里都有哪些子表实例（用于排查
+     *      "spec 拿到的 controller 是不是任务池主表，而不是 dialog 内的子表"）
+     *
+     * **关键设计**：这个 hook 失败时永不抛错——任何 try/catch 都吞掉；返回结构
+     * 字段可能为空但 shape 始终不变（spec 端可放心 JSON.stringify）。
+     *
+     * spec 调用建议：
+     * ```ts
+     * const probe = await page.evaluate(() => {
+     *   return (window as any).__CANVAS_TABLE_TEST_HOOKS__?.probeAmController?.();
+     * });
+     * console.log('[freeze-column/probe]', JSON.stringify(probe));
+     * ```
+     * （prefix 必须 `[freeze-column/probe]`，orchestrator 摘 observation 时按此匹配。）
+     *
+     * @returns 诊断对象；__AM_E2E__ 未挂时 available=false，其他字段为合理空值
+     */
+    probeAmController: () => {
+        available: boolean;
+        reason: string;
+        constructorName: string;
+        propsName: string;
+        tableType: string;
+        isMainPanel: boolean;
+        prototypeChain: string[];
+        freezeMethodsByLevel: Array<{
+            level: number;
+            className: string;
+            methods: string[];
+        }>;
+        freezeMethodsAll: string[];
+        typeofChecks: Record<string, string>;
+        byNameKeys: string[];
+        hasDataGrid: boolean;
+        hasTable: boolean;
+        /**
+         * task=f479647b/iter#3 新增：install 时间戳与计数器，给 spec 端算
+         * "spec 调用时机相对 hooks 安装时机"的偏移用。
+         *
+         * 字段含义：
+         *   - hooksInstalledAt      : Date.now() at first installTestHooks() call.
+         *                              (任何一个 DataGrid 实例第一次 mount 时被钉住)
+         *   - hooksLastInstalledAt  : Date.now() at most recent installTestHooks().
+         *                              (HMR / 多 DataGrid 时持续刷新)
+         *   - hooksInstallCount     : 累计 install 次数。
+         *   - nowAtProbe            : Date.now() at the moment probe is called.
+         *                              (spec 端算 nowAtProbe - hooksInstalledAt 即拿到偏移)
+         *   - hasHooksAlias         : window.__CANVAS_TABLE_TEST_HOOKS__ 是否真的指向某个 hooks。
+         *                              （正常 ≥ 1 install 之后必为 true）
+         *   - hasGridAlias          : window.__CANVAS_TABLE_GRID__ 是否真的指向某 DataGrid。
+         *                              （正常 ≥ 1 install 之后必为 true）
+         *
+         * 0 / false 表示未安装或浏览器无 Date.now（非常规环境）；spec 应把
+         * `hooksInstalledAt === 0` 当成"hooks 还没装"信号，不要 probe。
+         */
+        installTiming: {
+            hooksInstalledAt: number;
+            hooksLastInstalledAt: number;
+            hooksInstallCount: number;
+            nowAtProbe: number;
+            hasHooksAlias: boolean;
+            hasGridAlias: boolean;
+        };
     };
     findCellAreasByName: (taskName: string, columnDisplayName: string, options?: {
         scrollIfNeeded?: boolean;
@@ -694,6 +813,46 @@ export interface GroupRowAreas {
         rowId: string;
     };
 }
+/**
+ * AddTaskRow（⊕ 新建任务行）的 canvas 几何信息。
+ *
+ * task=be29ce06：`任务表格最后一行+号快速创建任务` 这个 e2e case 在 canvas 模式下
+ * 必须能精确点中 ⊕ 圆心，命中 `AddTaskRow.isInsideIconArea` 触发
+ * `grid.onAddRow → onCreateNewRow`。原本 spec 端按 `originFixedWidth/2 + 8` 估算
+ * 在 1D / 2D / 3D 分组下分别偏离 0 / 4 / 14 px，会落到行号区，触发 onRowClick 而
+ * 不是 onAddRow——本接口暴露的几何与 `AddTaskRow.isInsideIconArea` 一字不差对齐
+ * （含 `hitPadding=4`），保证"e2e 鼠标命中点 = AddTaskRow 运行时判定命中点"。
+ */
+export interface AddTaskRowArea {
+    /** AddTaskRow._rowId（一般是 `add_task_row_<rowIndex>` 或 String(data.id)） */
+    rowId: string;
+    /** body.data 内的 rowIndex（spec 调试 / log 用，不参与稳定 id 比较） */
+    rowIndex: number;
+    /** 行所属分组 id（非分组模式 / 该行无 groupId 时为 null） */
+    groupId: string | number | null;
+    /** _parentGroupLevel（非分组模式或未填时为 null；2D 第一层 = 0，第二层 = 1） */
+    parentGroupLevel: number | null;
+    /** 整行的 canvas 几何（行号 + 数据区，含右侧 verticalScrollerSize 之外） */
+    rowArea: AreaBounds;
+    /**
+     * ⊕ 图标命中区域（16×16 + hitPadding=4 → 实际 24×24），canvas 相对坐标。
+     *
+     * 几何与 `AddTaskRow.isInsideIconArea` 一字不差对齐：
+     *   bw = parentGroupLevel >= 0
+     *     ? maxGroupLevel === 0 ? 0
+     *       : (parentGroupLevel >= 2 ? l0w + l1w
+     *          : parentGroupLevel >= 1
+     *            ? (maxGroupLevel === 1 ? l0w : l0w + l1w)
+     *            : l0w)
+     *     : 0
+     *   iconX = bw + (originFixedWidth - bw - 16) / 2
+     *   center = (iconX + 8, rowAbsY + height/2)
+     *
+     * spec 拿到后用中心点 (canvasX + width/2, canvasY + height/2) → canvasToViewport
+     * → page.mouse.click 即可命中。
+     */
+    iconArea: AreaBounds;
+}
 /**
  * Row checkbox area for normal (non-group) data rows.
  *
@@ -779,5 +938,15 @@ declare global {
     interface Window {
         __CANVAS_TABLE_TEST_HOOKS__?: TestHooksAPI;
         __CANVAS_TABLE_TEST_HOOKS_REGISTRY__?: TestHooksRegistry;
+        /**
+         * task=f479647b/iter#3：installTestHooks 首次成功安装时的 Date.now()。
+         * spec 端可 `await page.waitForFunction(() => typeof window.__CANVAS_TABLE_TEST_HOOKS_INSTALLED_AT__ === 'number')`
+         * 等待 hooks 真正就绪，避免"isCanvasReady 早调一拍"的 race。
+         */
+        __CANVAS_TABLE_TEST_HOOKS_INSTALLED_AT__?: number;
+        /** task=f479647b/iter#3：最近一次 installTestHooks 时的 Date.now()（HMR / 多 grid 持续刷新）。 */
+        __CANVAS_TABLE_TEST_HOOKS_LAST_INSTALLED_AT__?: number;
+        /** task=f479647b/iter#3：installTestHooks 累计调用次数。 */
+        __CANVAS_TABLE_TEST_HOOKS_INSTALL_COUNT__?: number;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arthub-table",
-  "version": "0.2.6",
+  "version": "0.2.7-next.1",
   "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",