xiaodao-spreader 0.1.35 → 0.1.37

package/dist/types/components/spreader/core/outline-core.d.ts

@@ -0,0 +1,64 @@
+import type { DimensionOutline } from './types';
+/** 分组校验失败的原因 */
+export type OutlineValidationCode = 'outlineMinSize' | 'outlineCrossing' | 'outlineTooDeep' | 'outlineInvalid';
+export interface OutlineValidationResult {
+    ok: boolean;
+    code?: OutlineValidationCode;
+    /** 通过校验时，根据嵌套关系算出的层级（1 起） */
+    level?: number;
+}
+/** 范围内包含多少既有分组（严格包含该范围的组越多，层级越深） */
+export declare function countContaining(outlines: DimensionOutline[], start: number, end: number): number;
+/**
+ * 校验一个新分组（start/end 为 0-based 闭区间）是否可在既有分组集合上创建。
+ * 规则：
+ *   - start <= end
+ *   - 至少连续 2 个维度
+ *   - 与既有分组必须完全不相交，禁止部分重叠与嵌套（仅支持一层分组）
+ *   - 层级恒为 1（countContaining 必须为 0）
+ */
+export declare function validateGroup(existing: DimensionOutline[], start: number, end: number): OutlineValidationResult;
+/** 创建分组后的新集合（校验失败返回原集合，同时给出校验结果供调用方提示） */
+export declare function addOutline(existing: DimensionOutline[], axis: 'row' | 'column', start: number, end: number, id: string, opts?: {
+    collapsed?: boolean;
+}): {
+    outlines: DimensionOutline[];
+    validation: OutlineValidationResult;
+};
+/** 设置某个分组的折叠状态 */
+export declare function setOutlineCollapsed(outlines: DimensionOutline[], id: string, collapsed: boolean): DimensionOutline[];
+/** 删除某个分组（返回新集合） */
+export declare function removeOutline(outlines: DimensionOutline[], id: string): DimensionOutline[];
+/** 清除全部（某方向）分组 */
+export declare function clearOutlines(): DimensionOutline[];
+/** 插入 count 个维度到 index 处后，调整既有分组范围（完全遵循 Range 插入语义） */
+export declare function addOutlineForInsert(outlines: DimensionOutline[], index: number, count: number): DimensionOutline[];
+/** 删除 [index, index+count-1] 这段维度后，调整既有分组；空组自动移除 */
+export declare function addOutlineForDelete(outlines: DimensionOutline[], index: number, count: number): DimensionOutline[];
+/**
+ * 根据嵌套关系重建每个分组的 level：
+ * level = (严格包含该分组的其它分组数量) + 1
+ * 注意：必须排除自身，否则每个分组都会被自己计数导致层级 +1。
+ */
+export declare function recomputeOutlineLevels(outlines: DimensionOutline[]): DimensionOutline[];
+/**
+ * 维度可见性索引。
+ *  - levels[i]   : 维度 i 所处的 outline 层级（0 = 不在任何分组内）
+ *  - hidden[i]   : 维度 i 是否被某个「已折叠分组」包含（不可见）
+ *  - maxLevel    : 当前分组最深层级（≥1）；无分组为 0
+ */
+export interface OutlineIndex {
+    levels: number[];
+    hidden: boolean[];
+    maxLevel: number;
+}
+/** 构建线性维度（行/列）的 outline 索引。count = 维度总数 */
+export declare function buildOutlineIndex(outlines: DimensionOutline[], count: number): OutlineIndex;
+/** 维度 i 所处的 outline 层级（无分组为 0） */
+export declare function outlineLevelAt(outlines: DimensionOutline[], i: number): number;
+/** 维度 i 是否被某个已折叠分组包含（不可见） */
+export declare function isOutlineCollapsedAt(outlines: DimensionOutline[], i: number): boolean;
+/** 是否已存在跨过该分组 cell 的既有分组（按 cell 命中） */
+export declare function hasOutlineInRange(outlines: DimensionOutline[], start: number, end: number): boolean;
+/** 生成稳定唯一分组 ID（避免与既有 ID 冲突） */
+export declare function genOutlineId(existing: DimensionOutline[], axis: 'row' | 'column'): string;

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

@@ -252,6 +252,20 @@ export interface DataValidationResult {
     title?: string;
     message?: string;
 }
+/** 单个行列分组的最大支持层级：固定为 1，即仅支持一层分组（分组之间互不嵌套） */
+export declare const MAX_OUTLINE_LEVEL = 1;
+/** 维度分组：属于 Sheet 的结构元数据。start/end 为 0-based 闭区间，且 start <= end */
+export interface DimensionOutline {
+    /** 稳定唯一 ID（禁止数组 index） */
+    id: string;
+    axis: 'row' | 'column';
+    start: number;
+    end: number;
+    /** 由嵌套关系计算得到的层级（1 起），非用户手工输入 */
+    level: number;
+    /** 是否折叠（折叠时隐藏组内 Detail，逻辑行列仍存在） */
+    collapsed: boolean;
+}
 export interface SheetModelData {
     name: string;
     /** 表格级样式池：styles[0] 始终为默认空样式 {} */
@@ -278,6 +292,10 @@ export interface SheetModelData {
     conditionalFormats?: ConditionalFormattingRule[];
     /** 数据验证规则集合；旧数据缺省视为无数据验证 */
     dataValidations?: DataValidationRule[];
+    /** 行分组集合；旧数据缺省视为无分组 */
+    rowOutlines?: DimensionOutline[];
+    /** 列分组集合；旧数据缺省视为无分组 */
+    columnOutlines?: DimensionOutline[];
 }
 export interface SheetState {
     id: string;
@@ -306,6 +324,10 @@ export interface SheetState {
     conditionalFormats: ConditionalFormattingRule[];
     /** 数据验证规则集合；缺省为空数组 */
     dataValidations: DataValidationRule[];
+    /** 行分组集合；缺省为空数组 */
+    rowOutlines: DimensionOutline[];
+    /** 列分组集合；缺省为空数组 */
+    columnOutlines: DimensionOutline[];
 }
 /** 视口区域：冻结窗格将画布划分为四个独立滚动区域 */
 export interface ViewportRegion {
@@ -341,6 +363,8 @@ export interface ThemeColors {
     gridLine: string;
     selectionBg: string;
     activeCellBorder: string;
+    outlineGroupBg1: string;
+    outlineGroupBg2: string;
     cellText: string;
     scrollTrack: string;
     scrollThumb: string;

package/dist/types/components/spreader/core/utils.d.ts

@@ -24,3 +24,23 @@ export declare function getCanvasXY(e: MouseEvent, canvas: HTMLCanvasElement | n
 export declare function gridViewW(viewW: number, sbSize: number): number;
 /** 网格可视区域高度（减去行头和滚动条） */
 export declare function gridViewH(viewH: number, sbSize: number): number;
+/** 浮层可用的有效边界（视口坐标系）。
+ *
+ * 取「组件容器(boundaryEl)」∩「浏览器视口」的交集，两者都不能单独作为判据：
+ *   - 浏览器视口：浮层 Teleport 到 body + position:fixed，挂在视口坐标系，越出视口一定看不见（硬边界）。
+ *     但组件作为子组件嵌入宿主页面时只占页面一部分，纯视口判定会漏算两侧留白 → 越界盖住宿主内容。
+ *   - 组件容器：嵌入场景下把浮层夹在表格可视区内。但容器可能大于视口（页面滚动、边缘在视口外），
+ *     纯容器判定会把「其实已在视口外」当成有空间 → 浮层照样看不见。
+ *
+ * 取交集后：组件全屏时容器≈视口，自然退化为纯视口判定；boundaryEl 为空时同样退化为纯视口。
+ */
+export interface FloatBounds {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+export declare function getFloatBounds(boundaryEl?: HTMLElement | null): FloatBounds;
+/** 把「视口坐标 x」换算成 fixed 定位的 CSS `right` 值（相对视口右缘的偏移）。
+ *  浮层以 position:fixed 挂在视口坐标系，故换算基准恒为 window.innerWidth，与有效边界无关。 */
+export declare function cssRightFromX(x: number): number;