@xpyjs/gantt-core 0.0.3 → 0.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xpyjs/gantt-core",
   "private": false,
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "A powerful and flexible Gantt chart component library for modern web applications with TypeScript support",
   "type": "module",
   "main": "./dist/x-gantt.umd.cjs",

package/types/event/index.d.ts

@@ -87,5 +87,11 @@ export declare enum ErrorType {
     /** 无效参数 */
     LINK_INVALID_ARG = "LINK_INVALID_ARG",
     /** 检测到环 */
-    LINK_CYCLE = "LINK_CYCLE"
+    LINK_CYCLE = "LINK_CYCLE",
+    /** 移动目标无效 */
+    MOVE_INVALID_TARGET = "MOVE_INVALID_TARGET",
+    /** 移动产生循环依赖 */
+    MOVE_CIRCULAR_DEPENDENCY = "MOVE_CIRCULAR_DEPENDENCY",
+    /** 移动层级无效 */
+    MOVE_INVALID_HIERARCHY = "MOVE_INVALID_HIERARCHY"
 }

package/types/index.d.ts

@@ -9,5 +9,5 @@ import type { IOptions, IOptionConfig, EmitData } from "./types";
 import type { EventMap } from "./types/event";
 import type { ILink, DataChain, LinkType } from "./types/link";
 import type { ErrorType } from "./event";
-import type { XGanttUnit } from "./types/options";
-export type { IOptions, IOptionConfig, EmitData, EventMap, ILink, ErrorType, XGanttUnit, DataChain, LinkType };
+import type { XGanttUnit, DurationUnit, IScaleConfig, IScaleConfigBase, IScaleConfigBottom, ScaleUnit } from "./types/options";
+export type { IOptions, IOptionConfig, EmitData, EventMap, ILink, ErrorType, XGanttUnit, DurationUnit, IScaleConfig, IScaleConfigBase, IScaleConfigBottom, ScaleUnit, DataChain, LinkType };

package/types/rendering/Renderer.d.ts

@@ -10,6 +10,7 @@ export declare class Renderer {
     private table;
     private chart;
     private middleLine;
+    private guideLine;
     private renderScheduler;
     private _id;
     private width;

package/types/rendering/chart/ChartBody.d.ts

@@ -18,6 +18,15 @@ export declare class BodyGroup {
     private highlightRect;
     private selectedRowId;
     private selectedRect;
+    private boundHandleMouseMove;
+    private boundHandleMouseLeave;
+    private boundHandleClick;
+    private boundHandleDblClick;
+    private boundHandleContextMenu;
+    private onRowHighlight;
+    private onRowUnhighlight;
+    private onTaskSelected;
+    private onTaskUnselected;
     constructor(context: IContext, stage: Konva.Stage, layer: Konva.Layer, bgLayer: Konva.Layer);
     /**
      * 调整大小

package/types/rendering/chart/ChartGrid.d.ts

@@ -9,6 +9,10 @@ export declare class GridGroup {
     private height;
     private offsetX;
     private offsetY;
+    private renderedColStart;
+    private renderedColEnd;
+    private renderedRowStart;
+    private renderedRowEnd;
     constructor(context: IContext, layer: Konva.Layer);
     /**
      * 调整网格大小

package/types/rendering/chart/ChartHeader.d.ts

@@ -4,9 +4,13 @@ export declare class HeaderLayer {
     private context;
     private layer;
     private background;
-    private groupHeader;
-    private cellHeader;
+    private headerGroups;
+    private separatorLines;
     private cellCache;
+    private renderedStartX;
+    private renderedEndX;
+    /** 缓冲区比例：视口宽度的30%，左右各多渲染这么宽 */
+    private static readonly BUFFER_FACTOR;
     private width;
     private height;
     private offsetX;
@@ -29,9 +33,15 @@ export declare class HeaderLayer {
      */
     render(): void;
     /**
-     * 计算并绘制表头
+     * 构建表头结构（headerGroups + 分隔线）
+     * 仅在 resize 或数据变化时调用
      */
-    private calculateHeader;
+    private buildStructure;
+    /**
+     * 渲染表头 cell 内容（带缓冲区的可视范围裁剪）
+     * 滚动超出缓冲区时调用，重建 cells 但保留 group 结构
+     */
+    private renderCells;
     private createCell;
     /**
      * 清除表头内容

package/types/rendering/chart/ChartHoliday.d.ts

@@ -13,6 +13,8 @@ export declare class HolidayGroup {
     private offsetY;
     private holidayGroup;
     private patternImage;
+    /** 渲染版本号，用于丢弃过期的异步结果 */
+    private renderVersion;
     constructor(context: IContext, layer: Konva.Layer);
     /**
      * 调整假期大小

package/types/rendering/chart/ChartSlider.d.ts

@@ -59,4 +59,8 @@ export declare class ChartSlider {
     private handleBarHighlight;
     /** 闪烁 */
     private handleBarBlink;
+    /**
+     * 销毁滑块，清理所有定时器和资源
+     */
+    destroy(): void;
 }

package/types/rendering/chart/ChartWeekend.d.ts

@@ -14,6 +14,8 @@ export declare class WeekendGroup {
     private offsetY;
     private weekendGroup;
     private patternImage;
+    /** 渲染版本号，用于丢弃过期的异步结果 */
+    private renderVersion;
     constructor(context: IContext, layer: Konva.Layer);
     /**
      * 检查日期是否为周末

package/types/rendering/other/GuideLine.d.ts

@@ -8,6 +8,10 @@ export declare class GuideLine {
     private element;
     private container;
     private visible;
+    private onShowGuideline;
+    private onHideGuideline;
+    private onMoveGuideline;
+    private onOptionsUpdate;
     /**
      * @param container 指示线的容器元素
      */
@@ -51,4 +55,8 @@ export declare class GuideLine {
      * 更新参数
      */
     updateOptions(): void;
+    /**
+     * 销毁指示线，清理事件监听
+     */
+    destroy(): void;
 }

package/types/rendering/table/DragHandler.d.ts

@@ -17,10 +17,13 @@ export declare class DragHandler {
     private rowElement;
     constructor(context: IContext, container?: HTMLDivElement | undefined, task?: Task | undefined);
     private createElement;
+    private handleSelectStart;
     private bindEvents;
     private handleMouseDown;
     private handleMouseMove;
     private handleMouseUp;
+    /** ESC 取消拖拽的 keydown */
+    private handleKeyDown;
     /**
     * 创建拖拽跟随影像
     */

package/types/rendering/table/TableRow.d.ts

@@ -7,6 +7,15 @@ export declare class TableRow {
     private top;
     element: HTMLDivElement;
     private cells;
+    private handleMouseEnter;
+    private handleMouseLeave;
+    private handleClick;
+    private handleDblClick;
+    private handleContextMenu;
+    private onRowHighlight;
+    private onRowUnhighlight;
+    private onTaskSelected;
+    private onTaskUnselected;
     /**
      * 创建表格行
      * @param context 上下文

package/types/rendering/table/index.d.ts

@@ -11,5 +11,8 @@ export declare class Table {
     refresh(top: number, tasks: Task[]): void;
     updateWidth(): void;
     updateTask(task: Task): void;
+    private onUpdateTableHeader;
+    private onUpdateTableBody;
     private listenEvents;
+    destroy(): void;
 }

package/types/store/DataManager.d.ts

@@ -108,6 +108,10 @@ export declare class DataManager {
      * 更新子任务的层级
      */
     private updateChildrenLevel;
+    /**
+     * 重新计算所有任务的最大层级
+     */
+    private recalculateDataLevel;
     /**
      * 使缓存失效，标记需要重新生成扁平化任务列表
      */

package/types/store/TimeAxis.d.ts

@@ -1,6 +1,30 @@
 import dayjs, { type Dayjs } from "../utils/time";
-import { IGanttOptions } from "@/types/options";
-/** 表头项 */
+import { DurationUnit, IGanttOptions } from "@/types/options";
+/** 内部标准化后的 scale 配置 */
+export interface ParsedScale {
+    unit: DurationUnit;
+    step: number;
+    format?: string | ((date: Date, unit: DurationUnit, step: number) => string);
+    cellWidth?: number;
+    height?: number;
+}
+/** 时间线单元格项 */
+export interface TimelineCellItem {
+    /** 时间对象 */
+    date: Dayjs;
+    /** 展示的文本 */
+    label: string;
+    /** 跨越多少个最小渲染单位 */
+    span: number;
+    /** 是否隐藏 */
+    hide?: boolean;
+}
+/** 时间线层 */
+export interface TimelineLayer {
+    scale: ParsedScale;
+    items: TimelineCellItem[];
+}
+/** 表头项（旧接口，保持兼容） */
 export interface TimelineItem {
     /** 时间对象 */
     date: Dayjs;
@@ -22,25 +46,52 @@ export declare class TimeAxis {
     private strictEnd;
     /** 是否自适应宽度 */
     private isAuto;
-    /** 表头的日期列表 */
-    private timeline;
-    private headerGroupFormat?;
-    private headerCellFormat?;
+    /** N 层时间线缓存 */
+    private timelineLayers;
     private isDirty;
     /** 是否第一次赋值，如果第一次赋值，允许全部赋值 */
     private isFirstTime;
     /** 总宽度 */
     private allWidth;
-    /** 每一格的宽度 */
-    private cellWidth;
-    /** 用户设定的单位 */
+    /** 内部标准化后的 scales */
+    private scales;
+    /** 是否旧模式（未使用 scaleUnit） */
+    private isLegacyMode;
+    /** 旧模式下的 cellWidth 映射 */
+    private legacyCellWidthMap;
+    /** 新模式下的 cellWidth（px/最小渲染单位） */
+    private _resolvedCellWidth;
+    /** 各层解析后的行高（px） */
+    private _resolvedLayerHeights;
+    /** 解析后的实际 header 高度（可能因 scaleUnit.height 溢出而扩展） */
+    private _resolvedHeaderHeight;
+    /** 旧模式记录的 unit */
     private unit;
+    /** 旧模式的 headerGroupFormat / headerCellFormat */
+    private headerGroupFormat?;
+    private headerCellFormat?;
     constructor();
     getStartTime(): dayjs.Dayjs;
     getEndTime(): dayjs.Dayjs;
+    /** 获取每个最小渲染单位的像素宽度（语义不变） */
     getCellWidth(): number;
+    /** 获取底层 timeline 的总 cell 数 */
     getCellCount(): number;
-    getCellUnit(): "day" | "hour";
+    /** 获取最小渲染单位 */
+    getCellUnit(): "hour" | "day";
+    /** 获取内部标准化后的 scales */
+    getScales(): ParsedScale[];
+    /** 获取底层 scale */
+    getBottomScale(): ParsedScale;
+    /** 获取各层解析后的行高（px） */
+    getLayerHeights(): number[];
+    /** 获取解析后的实际 header 高度 */
+    getResolvedHeaderHeight(): number;
+    /**
+     * 获取底层一格的像素宽度
+     * 用于 ChartHeader/Grid 绘制底层 cell 的宽度
+     */
+    getBottomCellWidth(date?: Dayjs): number;
     setAllWidth(width: number): void;
     getTimeLeft(time: Dayjs): number;
     /**
@@ -52,25 +103,9 @@ export declare class TimeAxis {
     init(options: IGanttOptions, isFirstTime?: boolean): void;
     update(options: IGanttOptions): void;
     setDate(start?: Dayjs, end?: Dayjs): void;
-    /** 获取表头的日期列表 */
-    getTimeline(): TimelineItem[];
+    /** 获取 N 层时间线数据 */
+    getTimeline(): TimelineLayer[];
     clear(): void;
-    /**
-     * 缓存失效标记
-     */
-    private invalidateCache;
-    /** 获取细粒度单位 */
-    private getFinelyUnit;
-    /** 获取下层单位 */
-    private getChildUnit;
-    /** 获取上层单位 */
-    private getGroupUnit;
-    /** 格式化上层文本 */
-    private formatterGroupLabel;
-    /**
-     * 格式化下层文本
-     */
-    private formatterCellLabel;
     /**
      * 获取时间轴的总宽度
      * @returns 时间轴总宽度（像素）
@@ -83,4 +118,50 @@ export declare class TimeAxis {
      * @returns 是否在时间轴上
      */
     isInTimeAxis(time: Dayjs): boolean;
+    /**
+     * 计算一个 scale cell 包含多少个最小渲染单位
+     * @param scale scale 配置
+     * @param date 日期（用于月/季度等变长单位）
+     */
+    getUnitsPerCell(scale: ParsedScale, date?: Dayjs): number;
+    /** 缓存失效标记 */
+    private invalidateCache;
+    /** 获取最小渲染单位：scales 中含 hour/minute → 'hour'，否则 → 'day' */
+    private getMinimumUnit;
+    /** 旧 unit → 内部 scales 自动转换 */
+    private legacyUnitToScales;
+    /** 每层最小行高 */
+    private static readonly MIN_SCALE_ROW_HEIGHT;
+    /**
+     * 解析各层行高。
+     *
+     * 规则：
+     * - 未指定 height 的层平分剩余空间
+     * - 指定的 height < MIN_SCALE_ROW_HEIGHT 时钳位
+     * - 所有指定层的 height 之和超过 headerHeight 时，自动扩展 headerHeight
+     * - 所有层均指定 height 且总和 < headerHeight 时，上对齐，底部留空白
+     */
+    private resolveLayerHeights;
+    /** 从 chart.cellWidth 解析新模式下的 cellWidth 值 */
+    private resolveCellWidthFromChart;
+    /**
+     * 将 cursor 对齐到 scale 的自然步进边界。
+     *
+     * step=1 时，直接 startOf(unit)。
+     * step>1 时，以"父周期"为锚点，向前找到最近的 step 整数倍边界。
+     * 例如 { unit:"hour", step:8 } → 一天内的自然边界为 0:00 / 8:00 / 16:00，
+     * cursor=15:00 时对齐到 8:00，首格 8:00→16:00 会被 calculateSpan 裁剪为
+     * startTime→16:00 的不完整格，后续格保持不变。
+     */
+    private alignToScaleStart;
+    /** 推进 cursor 到下一个 cell */
+    private advanceCursor;
+    /** 计算 cursor 到 cellEnd 之间跨越了多少个最小渲染单位 */
+    private calculateSpan;
+    /** 格式化标签 */
+    private formatLabel;
+    /** 获取默认格式化 */
+    private getDefaultFormat;
+    /** 获取一个季度的天数 */
+    private getQuarterDays;
 }

package/types/types/chart.d.ts

@@ -1,6 +1,15 @@
 import { XGanttUnit } from "./options";
 
 export interface IChartOptions {
+  /**
+   * 是否显示垂直网格线
+   *
+   * @default false
+   *
+   * @description 仅对 scaleUnit 参数生效。其余仍然为默认情况。
+   */
+  showVerticalLine?: boolean;
+
   /**
    * 开始时间。强制设置开始时间，覆盖数据中的开始时间。
    *

package/types/types/options.d.ts

@@ -7,6 +7,81 @@ import { ITableOptions } from "./table";
 export type XGanttUnit = "hour" | "day" | "week" | "month" | "quarter";
 export type TaskType = "task" | "milestone" | "summary";
 
+/** 所有支持的时间刻度单位 */
+export type DurationUnit = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+/**
+ * 时间轴刻度的基础配置
+ *
+ * @description 用于自定义时间轴的刻度显示。每个配置项定义一个表头层级。
+ * 数组从上（粗粒度）到下（细粒度）排列，最后一项为底层刻度。
+ */
+export interface IScaleConfigBase {
+  /** 时间单位 */
+  unit: DurationUnit;
+
+  /**
+   * 步长：每格合并几个 unit。
+   *
+   * @default 1
+   *
+   * @example step: 8, unit: 'hour' → 每格8小时
+   * @example step: 2, unit: 'week' → 每格2周
+   * @example step: 15, unit: 'day' → 每格15天
+   */
+  step?: number;
+
+  /**
+   * 标签格式化
+   *
+   * @description 字符串：使用 dayjs format 字符串
+   * @description 函数：(date: Date, unit: DurationUnit, step: number) => string
+   * @description 未指定时使用默认格式
+   */
+  format?: string | ((date: Date, unit: DurationUnit, step: number) => string);
+
+  /**
+   * 该层表头行高（px）。
+   *
+   * @description 取值最小为 20px，低于该值会被钳位。
+   * @description 未指定时，由 `header.height` 减去已指定层的高度后在未指定层中平分。
+   * @description 应当确保所有层高总和不小于 `header.height`。
+   * @description 如果所有层指定的高度之和超过 `header.height`，则 `header.height` 会自动扩展。
+   */
+  height?: number;
+
+  /** 非底层 scale 不允许设置 cellWidth */
+  cellWidth?: never;
+}
+
+/**
+ * 最下层时间轴刻度配置（scaleUnit 数组的最后一项）
+ *
+ * @description 底层 scale 允许设置 cellWidth，用于指定每格的像素宽度。
+ */
+export interface IScaleConfigBottom extends Omit<IScaleConfigBase, 'cellWidth'> {
+  /**
+   * 该层每格的宽度（px）。仅对底层 scale（scaleUnit 数组最后一项）生效。
+   *
+   * 非底层 scale 的宽度由其包含的底层 cell 数决定。
+   *
+   * 优先级：`scaleUnit[].cellWidth` > `chart.cellWidth`。
+   * 当底层 scale 指定了 cellWidth 时，将忽略 `chart.cellWidth` 配置；
+   * 未指定时，回退到 `chart.cellWidth` 按最小渲染单位推导。
+   */
+  cellWidth?: number;
+}
+
+/**
+ * 单层时间轴刻度配置
+ */
+export type IScaleConfig = IScaleConfigBase | IScaleConfigBottom;
+
+/**
+ * 自定义时间轴刻度配置
+ */
+export type ScaleUnit = [...IScaleConfigBase[], IScaleConfigBottom];
+
 export interface IGanttOptions {
   /** 日志 level。 默认 warn */
   logLevel?: "debug" | "info" | "warn" | "error" | "none";
@@ -525,9 +600,46 @@ export interface IGanttOptions {
    * 时间刻度
    *
    * @default 'day'
+   *
+   * // TODO: [future-major] unit 字段将被 scaleUnit 替代
    */
   unit: XGanttUnit;
 
+  /**
+   * 自定义时间轴刻度配置。定义 N 层表头，从上（粗粒度）到下（细粒度）排列。
+   *
+   * 提供后将忽略 `unit`、`chart.headerGroupFormat`、`chart.headerCellFormat`。
+   *
+   * @example
+   * // 8小时一格
+   * scaleUnit: [
+   *   { unit: 'day', step: 1, format: 'MM-DD ddd' },
+   *   { unit: 'hour', step: 8, format: 'HH:mm' }
+   * ]
+   *
+   * @example
+   * // 单层表头
+   * scaleUnit: [
+   *   { unit: 'month', step: 1, format: 'YYYY-MM' }
+   * ]
+   *
+   * @example
+   * // 三层表头
+   * scaleUnit: [
+   *   { unit: 'year', step: 1 },
+   *   { unit: 'month', step: 1 },
+   *   { unit: 'day', step: 1 }
+   * ]
+   *
+   * @example
+   * // 指定底层 cellWidth（仅最后一项允许设置）
+   * scaleUnit: [
+   *   { unit: 'week', step: 1, format: 'YYYY 第ww周' },
+   *   { unit: 'day', step: 1, format: 'DD', cellWidth: 50 }
+   * ]
+   */
+  scaleUnit?: ScaleUnit;
+
   /**
    * 显示语言。配置参考 {@link https://day.js.org/docs/en/i18n/i18n|dayjs i18n}
    *

package/types/utils/sanitize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 清理 HTML 字符串，移除潜在的 XSS 攻击载荷。
+ *
+ * 清理规则：
+ * - 移除危险标签（script, iframe, object 等）
+ * - 移除所有 on* 事件处理器属性
+ * - 移除 javascript: 协议的 URL
+ *
+ * @param html 待清理的 HTML 字符串
+ * @returns 清理后的安全 HTML 字符串
+ */
+export declare function sanitizeHtml(html: string): string;