docs: add code abbitation and technical docs

Author: fangsmile

packages/vtable/docs/frozen-area-scroll-design.md

@@ -0,0 +1,176 @@
+# 冻结区域独立横向滚动：技术设计
+
+本文总结 VTable 中“冻结区域（左冻结/右冻结）支持独立横向滚动”的实现设计、核心数据结构、关键链路改动点与边界行为。
+
+> 对应实现主要落在 packages/vtable/src 内；PR 参考：#5063（Feat/frozen column scroll）。
+
+## 1. 背景与问题
+
+在 ListTable 中，冻结列用于保持关键列常驻可见。但当冻结列总宽度超过最大冻结宽度（`maxFrozenWidth`）时，既有策略通常是“自动解冻部分列”以满足视口宽度限制。
+
+在一些业务场景中，冻结列必须保留（例如左侧关键标识列、右侧操作列），因此需要：
+
+- 冻结区域在宽度受限时仍保留全部冻结列
+- 在冻结区域内部提供横向滚动能力（与 body 横向滚动相互独立）
+- 在多滚动域场景下，滚动条显隐与交互需要“按区域”工作，避免混乱
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+- 新增左/右冻结区域内部横向滚动能力（trackpad/wheel 与滚动条拖拽/点击轨道）
+- 保持冻结区域“视口宽度”可控（左：`maxFrozenWidth`，右：`maxRightFrozenWidth`）
+- 多滚动域并存时（body / leftFrozen / rightFrozen），保证：
+  - 渲染坐标系正确（内容随各自 scrollLeft 平移）
+  - 命中坐标正确（getCellAt、事件 target 等与渲染一致）
+  - 主滚动条与冻结滚动条互不干扰
+  - `scrollStyle.visible` 为 `focus/scrolling/always/none` 时行为一致
+
+### 2.2 非目标
+
+- 本设计不覆盖 PivotTable/Gantt 的冻结滚动扩展（当前以 ListTable 为主）
+- 不引入插件化实现（该能力需要穿透状态/布局/命中/scenegraph 多层链路）
+
+## 3. 概念与术语
+
+- **冻结内容宽（content width）**：冻结列本身的总宽度，不受 maxFrozenWidth 限制。
+- **冻结视口宽（viewport width）**：冻结区域在画布上占用的宽度，受 maxFrozenWidth / maxRightFrozenWidth 限制。
+- **冻结溢出量（offset）**：`max(0, contentWidth - viewportWidth)`，表示冻结区域内部最大可滚动距离。
+- **滚动域（scroll domain）**：
+  - `body`：主横向滚动域（影响非冻结列）
+  - `frozen`：左冻结区域内部横向滚动域
+  - `rightFrozen`：右冻结区域内部横向滚动域
+
+## 4. 对外配置与 API
+
+### 4.1 新增配置（ListTableConstructorOptions）
+
+- `scrollFrozenCols?: boolean`
+  - `false`（默认）：冻结列超出最大冻结宽度时遵循原策略（可能解冻）
+  - `true`：冻结区域内部可横向滚动，保留全部冻结列
+- `maxRightFrozenWidth?: number | string`
+  - 右侧最大冻结宽度，默认与 `maxFrozenWidth` 对齐
+- `scrollRightFrozenCols?: boolean`
+  - `false`（默认）：右冻结区域宽度 = 内容宽度（无内部滚动）
+  - `true`：右冻结区域内部可横向滚动
+
+### 4.2 相关方法（BaseTable）
+
+左冻结：
+
+- `getFrozenColsContentWidth()`：冻结内容宽
+- `getFrozenColsWidth()`：冻结视口宽（scrollFrozenCols 开启时受 maxFrozenWidth 限制）
+- `getFrozenColsOffset()`：溢出量（最大可滚动距离）
+- `getFrozenColsScrollLeft()`：当前左冻结 scrollLeft（px）
+
+右冻结：
+
+- `getRightFrozenColsContentWidth()`
+- `getRightFrozenColsWidth()`（scrollRightFrozenCols 开启时受 maxRightFrozenWidth 限制）
+- `getRightFrozenColsOffset()`
+- `getRightFrozenColsScrollLeft()`
+
+## 5. 数据结构（StateManager）
+
+在 StateManager 中新增两个横向位置用于维护冻结域滚动：
+
+- `scroll.frozenHorizontalBarPos`：左冻结 scrollLeft（px）
+- `scroll.rightFrozenHorizontalBarPos`：右冻结 scrollLeft（px）
+
+并提供两类接口：
+
+1) 外部“设置滚动位置”（用于 wheel / click 轨道 / 拖拽）
+- `setFrozenColsScrollLeft(left, triggerRender?)`
+- `setRightFrozenColsScrollLeft(left, triggerRender?)`
+
+2) 外部“按滚动条 ratio 更新”（scrollDrag 回调给的是 range，需要映射回 scrollLeft）
+- `updateFrozenHorizontalScrollBar(xRatio)`
+- `updateRightFrozenHorizontalScrollBar(xRatio)`
+
+右冻结的 ratio 与 left 做了反向映射（`ratio = 1 - left/maxScrollLeft`），以更符合“右冻结内容从右向左展开”的视觉直觉。
+
+## 6. 渲染与布局（Scenegraph）
+
+### 6.1 左冻结
+
+左冻结的平移相对直观：冻结区域内部滚动时，对应 group 的 childrenX 直接使用 `-scrollLeft`。
+
+### 6.2 右冻结
+
+右冻结的布局基准是“内容右对齐视口”，因此需要同时考虑溢出量 offset 与 scrollLeft：
+
+- `rightFrozenStartX = -rightFrozenOffset + rightFrozenScrollLeft`
+
+含义：
+
+- `-offset`：使右冻结内容尾部对齐到视口右侧（把超出部分整体向左移出视口）
+- `+scrollLeft`：在视口内左右移动查看隐藏的列
+
+对应更新点：
+
+- `Scenegraph.updateContainerAttrWidthAndX()` 在布局刷新时更新 rightFrozenGroup / corner group 的 childrenX
+- `Scenegraph.setRightFrozenColsScrollLeft()` 在右冻结滚动变化时更新 rightFrozenGroup / rightTopCorner / rightBottomCorner 的 childrenX
+
+### 6.3 Clip（裁剪）
+
+多区域 overlay/内容组均依赖 clipRect 进行裁剪。右冻结视口宽度在开启 scrollRightFrozenCols 时不再等于内容宽度，需要使用 `getRightFrozenColsWidth()` 作为 clip 宽度来源，保证“内容滚动但不越界绘制”。
+
+## 7. 命中与坐标映射（HitTest）
+
+冻结区域内部滚动会改变“可视坐标 ↔ 内容坐标”的映射关系，因此需要在命中链路中补偿：
+
+- 右冻结命中：当 x 落在右冻结视口范围内时，先将 `absoluteX -= rightFrozenScrollLeft` 再计算 target col
+- 右冻结列 x 计算：`getColX(col, table, true)` 叠加 `getRightFrozenColsScrollLeft()`，保证渲染坐标与 hitTest 一致
+
+## 8. 事件分发（Wheel/Trackpad）
+
+横向 wheel 需要判断“滚动意图属于哪个滚动域”：
+
+- 优先冻结域：当指针坐标落在左冻结/右冻结视口范围内且该域可滚动（offset>0）
+- 否则落入 body 域
+
+注意：部分环境 wheel 事件可能没有可靠的 x/y，因此引入 LastBodyPointerXY 作为回退坐标。
+
+右冻结域的 delta 需要反向映射：
+
+- `rightFrozenDelta = -optimizedDeltaX`
+
+原因是右冻结内容的“展开方向”与 body/左冻结相反（内容从右向左展开）。
+
+## 9. 滚动条系统（ScrollBar UI）
+
+### 9.1 多段横向滚动条
+
+当左右冻结域启用内部滚动且存在溢出时，底部会出现三段横向滚动条：
+
+- body 主滚动条（hScrollBar）
+- 左冻结横向滚动条（frozenHScrollBar）
+- 右冻结横向滚动条（rightFrozenHScrollBar）
+
+各段的 range（滑块长度）分别反映其域的“视口宽 / 内容宽”。
+
+### 9.2 显隐策略与交互
+
+`scrollStyle.visible` 在多滚动域场景下的定义：
+
+- `always`：所有可滚动域的滚动条同时显示
+- `focus`：只显示指针所在域的滚动条（避免干扰）
+- `scrolling`：滚动发生时显示；hover 到滚动条区域时显示以支持交互；离开后延迟隐藏
+
+实现上通过 `TableComponent.showHorizontalScrollBar(target)` 控制显示目标域，并在事件监听中根据 hover/scrolling 规则维护 autoHide。
+
+## 10. 关键边界与已处理问题
+
+- **右冻结分割线（shadow line）错位**：当右冻结内容可滚动时，分割线应固定在“右冻结视口左边界”而不是随内容滚动
+- **选区 overlay 被裁切**：当选区贴边或存在 fill handle 时，需要对 overlay 的 clipRect 进行外扩（详见选框技术设计文档）
+- **拖拽滚动条不生效**：throttle 绑定函数需要 bind(this)，否则 this.table 不可用
+
+## 11. 可观测性与测试建议
+
+建议覆盖以下用例：
+
+- 左冻结溢出：trackpad 横向滚动仅影响左冻结内容；body 不动
+- 右冻结溢出：trackpad 横向滚动方向符合预期；命中列与渲染一致
+- 滚动条：三段滚动条的滑块比例正确；拖拽与点击轨道能驱动对应域滚动
+- visible 策略：focus/scolling 下仅显示目标域滚动条且可自动隐藏
+

packages/vtable/docs/select-border-design.md

@@ -0,0 +1,171 @@
+# 选框（Select Border）改造：技术设计（前/后对比）
+
+本文总结 VTable 选框（selection border + fill handle）的设计背景、改造前的问题、改造后的结构与关键实现点，便于后续维护与扩展。
+
+> 涉及代码：packages/vtable/src/scenegraph/select/* 及 overlay clip 相关贡献逻辑。
+
+## 1. 背景
+
+VTable 的“选框”由两个主要视觉元素组成：
+
+- **selection border**：选区外边框（可配置边框色、线宽、虚线等）
+- **fill handle**：右下角 6x6 小方块（Excel 类填充柄），受 `excelOptions.fillHandle` 控制
+
+在引入“冻结区域独立滚动”后，表格的可视区域被拆成多个区域（body/headers/leftFrozen/rightFrozen/bottomFrozen），选框需要：
+
+- 正确出现在对应区域的 overlay 层并被 clip 裁剪
+- 支持跨区域选择（需要拆分多段绘制）
+- 避免在跨区域边界重复描边（导致边框变粗）
+- 在贴边/裁剪边界时不出现“半条线”或 fill handle 被切掉
+
+## 2. 改造前设计（概念层面）
+
+### 2.1 选框的基本组织方式
+
+- 选框图元挂在 overlayGroup 下（select-overlay），overlayGroup 会被各区域 clipRect 裁剪。
+- 对于跨区域选区，会拆分为多个选框段落（每段一个 rect，必要时一个 fill handle）。
+
+### 2.2 主要痛点
+
+1) **贴边裁剪导致的边框缺失**
+- 选框的描边线宽是以 rect 边界为中心绘制；当选区贴着表格边缘或区域 clip 边界时，一半线宽会被裁剪，呈现“半条线”。
+
+2) **fill handle 被裁剪或定位异常**
+- 在最后一行/最后一列等边界场景，fill handle 可能落到 clip 外，导致不可见或难以命中。
+
+3) **跨区域选框的重复描边**
+- 选区跨越多个 overlay（例如 columnHeader + body，或 body + rightFrozen）时，如果各段都绘制相邻边，会在边界处叠加出更粗的边框。
+
+4) **场景树重建导致选区丢失**
+- 数据更新导致 scenegraph 重建时，overlay 下的选区图元会被清空，需要从 state 恢复。
+
+## 3. 改造后设计（实现层面）
+
+改造后的原则：
+
+- **跨区域必拆分**：按区域拆分为多段选框，每段只负责自己的绘制与裁剪
+- **边界不重复描边**：通过 strokeArray 控制每段四边是否绘制
+- **贴边不裁半线**：在选框更新时对 rect 做“半线宽补偿”，同时对 overlay clipRect 做“外扩”
+- **fill handle 只在可解释场景出现**：单选区 + 非表头 + 边不被禁用时显示
+
+## 4. 关键实现点
+
+### 4.1 选框创建：overlay 坐标换算与 fill handle 显示条件
+
+文件：
+
+- packages/vtable/src/scenegraph/select/create-select-border.ts
+
+要点：
+
+- 使用 `highPerformanceGetCell(...).globalAABBBounds` 获取单元格全局边界，再减去 `tableGroup + overlayGroup` 的偏移，换算成 overlay 本地坐标。
+- fill handle 的显示需要满足：
+  - `excelOptions.fillHandle` 开启
+  - 当前仅 1 个选区（多选区时移除所有 handle）
+  - 选区不包含表头（header 不允许填充）
+  - strokes 中右边或下边被关闭时不显示（避免 handle 由其它段负责时重复出现）
+
+### 4.2 选框更新：可视范围裁剪与 fill handle 边界定位
+
+文件：
+
+- packages/vtable/src/scenegraph/select/update-select-border.ts
+
+要点：
+
+1) **按 role 裁剪计算范围**
+
+不同区域的选框更新策略不同：
+
+- `rowHeader`：只裁剪行范围（跟随 body 可视行）
+- `columnHeader` / `bottomFrozen`：只裁剪列范围（跟随 body 可视列）
+- `rightFrozen`：只裁剪行范围（跟随 body 可视行）
+- `body`：裁剪行列范围
+
+目的是避免更新不可见区域的选框段落，降低滚动过程的更新开销。
+
+2) **fill handle 边界推导**
+
+当选区触达最后一列/最后一行时，直接取 “end cell bound” 可能导致 handle 超出 clip。实现上通过相邻单元格的 bound 推导 `handlerX/handlerY`，让 handle 保持在可见边界附近。
+
+3) **贴边半线宽裁切修正**
+
+当选区贴着表格外边界时，通过根据 lineWidth 计算 diffSize，对 rect 做 x/y/width/height 的微调，避免“半条线”现象。
+
+### 4.3 跨区域拆分：calculateCellRangeDistribution + strokeArray
+
+文件：
+
+- packages/vtable/src/scenegraph/select/update-select-border.ts
+- packages/vtable/src/scenegraph/select/update-custom-select-border.ts
+
+流程：
+
+1) `calculateCellRangeDistribution(startCol, startRow, endCol, endRow, table)` 判断选区跨越哪些区域。
+2) 针对每个需要的区域创建一段选框，传入该段负责的范围。
+3) 通过 `strokeArray=[top,right,bottom,left]` 控制该段四边是否绘制，避免跨区域边界重复描边。
+
+自定义选框（CustomSelectionStyle）沿用相同的拆分策略，但只绘制 rect，不包含 fill handle。
+
+### 4.4 selecting → selected 的提交语义
+
+文件：
+
+- packages/vtable/src/scenegraph/select/move-select-border.ts
+
+语义：
+
+- `selectingRangeComponents` 表示“拖拽中”的临时选框
+- 鼠标松开后需要迁移到 `selectedRangeComponents`，作为稳定的选中态
+- 若同 key 已存在历史段落，先 delete 避免泄漏与重复绘制
+
+### 4.5 删除逻辑：shift 续选与 fill handle 清理
+
+文件：
+
+- packages/vtable/src/scenegraph/select/delete-select-border.ts
+
+要点：
+
+- 通过 `scene.lastSelectId` 识别“上一次选择动作”产生的所有段落（跨区域拆分时 selectId 相同）
+- shift 续选需要删除上一次选择段落，再追加新的段落
+- 多选区时需要统一移除 fill handle
+
+### 4.6 overlay 裁剪外扩：避免边框与 fill handle 被 clip 截断
+
+文件：
+
+- packages/vtable/src/scenegraph/graphic/contributions/group-contribution-render.ts
+
+要点：
+
+- overlay（select-overlay）组会被各区域 clipRect 裁剪
+- 对 overlay 的 clipRect 进行“外扩”（inflate）：
+  - baseInflate：覆盖 selection border 的线宽
+  - handleInflate：当开启 fill handle 且只有一个选区时，为 6x6 handle 预留空间（3px）
+
+这一层和 4.2 的贴边修正配合，解决“线宽/handle 被裁切”的可见性问题。
+
+### 4.7 场景树重建后的选区恢复
+
+文件：
+
+- packages/vtable/src/scenegraph/scenegraph.ts
+
+要点：
+
+- 数据更新触发 scenegraph 重建会清空 overlay 下的选区图元
+- 若 state 中仍存在 select ranges，需要在场景树重建完成后重新创建选区组件，保证选中态不丢失
+
+## 5. 行为对比（摘要）
+
+- 改造前：选区贴边时边框/handle 可能被裁，跨区域容易重复描边，scenegraph 重建后可能丢失选区图元。
+- 改造后：通过“跨区域拆分 + strokeArray 去重 + overlay clip 外扩 + 贴边半线宽修正 + 重建后恢复”保证一致性与可维护性。
+
+## 6. 测试建议
+
+- 单选区 + fill handle：拖拽到最后一行/最后一列仍可见且可命中
+- 多选区：fill handle 不出现，且历史 handle 会被清理
+- 跨区域选择：跨表头/左冻结/右冻结/底部冻结时边框不加粗
+- scrollFrozenCols/scrollRightFrozenCols 开启：滚动冻结域时选框与 handle 不被裁切、不漂移
+

packages/vtable/src/core/BaseTable.ts

@@ -3014,21 +3014,26 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
    */
   getFrozenColsWidth(): number {
     const contentWidth = this.getFrozenColsContentWidth();
+    // frozenColsWidth 表示“冻结区域视口宽度”，可能小于冻结列内容总宽。
+    // 当开启 scrollFrozenCols 时，冻结区域会限制到 maxFrozenWidth，并允许在冻结区域内部横向滚动来查看超出部分。
     if (!this.options.scrollFrozenCols) {
       return contentWidth;
     }
     const maxFrozenWidth = this._getMaxFrozenWidth();
     return Math.min(contentWidth, maxFrozenWidth);
   }
   getFrozenColsContentWidth(): number {
+    // 冻结列内容总宽（不受 maxFrozenWidth 限制）
     return this.getColsWidth(0, this.frozenColCount - 1);
   }
   getFrozenColsOffset(): number {
+    // 冻结区域可滚动的最大距离（内容宽 - 视口宽），用于计算滚动条范围与边界判断
     const contentWidth = this.getFrozenColsContentWidth();
     const viewportWidth = this.getFrozenColsWidth();
     return Math.max(0, contentWidth - viewportWidth);
   }
   getFrozenColsScrollLeft(): number {
+    // 左冻结区域内部的横向滚动位置（像素值）
     return this.stateManager.scroll.frozenHorizontalBarPos ?? 0;
   }
   /**
@@ -3052,6 +3057,8 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
    */
   getRightFrozenColsWidth(): number {
     const contentWidth = this.getRightFrozenColsContentWidth();
+    // rightFrozenColsWidth 表示“右侧冻结区域视口宽度”。
+    // 当开启 scrollRightFrozenCols 时，右侧冻结区域会限制到 maxRightFrozenWidth，并允许在右冻结区域内部横向滚动。
     if (!this.options.scrollRightFrozenCols) {
       return contentWidth;
     }
@@ -3069,11 +3076,13 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
     return 0;
   }
   getRightFrozenColsOffset(): number {
+    // 右侧冻结区域可滚动的最大距离（内容宽 - 视口宽）
     const contentWidth = this.getRightFrozenColsContentWidth();
     const viewportWidth = this.getRightFrozenColsWidth();
     return Math.max(0, contentWidth - viewportWidth);
   }
   getRightFrozenColsScrollLeft(): number {
+    // 右冻结区域内部的横向滚动位置（像素值）
     return this.stateManager.scroll.rightFrozenHorizontalBarPos ?? 0;
   }
   /**