ct-gantt-core 1.0.14 → 1.0.16

package/README.md

@@ -1,83 +1,98 @@
-# ct-gantt-core
-
-框架无关的甘特图数据、布局、依赖排程和命令式引擎。该包不包含界面，可用于 Vue、React、原生 JavaScript、服务端计算或自定义渲染器。
-
-## 安装
-
-```bash
-pnpm add ct-gantt-core
-```
-
-也可以使用 `npm install ct-gantt-core` 或 `yarn add ct-gantt-core`。
-
-## 最小示例
-
-```ts
-import { GanttEngine, type GanttTask } from "ct-gantt-core"
-
-const tasks: GanttTask[] = [
-  {
-    id: "task-1",
-    name: "需求分析",
-    type: "task",
-    plan: { start: "2026-07-01", end: "2026-07-05" },
-    actual: { start: "2026-07-01", end: "2026-07-06", progress: 60 }
-  }
-]
-
-const engine = new GanttEngine({
-  tasks,
-  config: { viewMode: "day", columnWidth: 30 }
-})
-
-const layout = engine.getLayout()
-if (layout.ok) {
-  console.log(layout.data)
-}
-
-engine.setTask("task-1", { progress: 80 })
-engine.destroy()
-```
-
-## 依赖排程
-
-```ts
-import { scheduleByDependencies, type GanttLink } from "ct-gantt-core"
-
-const links: GanttLink[] = [
-  { id: "design-to-dev", sourceId: "design", targetId: "dev", type: "FS" }
-]
-
-const result = scheduleByDependencies(tasks, links)
-if (result.ok) {
-  console.log(result.data)
-}
-```
-
-支持 `FS`、`SS`、`FF`、`SF` 四种依赖类型，以及自然日或工作日间隔。
-
-## 主要导出
-
-| API | 用途 |
-| --- | --- |
-| `GanttEngine` | 管理任务、依赖、折叠、预览、布局和视口命令 |
-| `computeLayout` | 计算任务条位置和尺寸 |
-| `computeTimeScale` | 计算时间刻度（day/week/month/quarter/year） |
-| `computeHourScale` | 计算小时级时间刻度（每天 24 个小时列，顶行日期 + 底部整点小时） |
-| `computeResourceLayout` | 资源视图布局：资源行 + 占用色条（支持 day/hour 粒度与车道堆叠） |
-| `resolveUsageTimes` | 将资源占用解析为布局用起止时间（hour 粒度下纯日期占用含结束日整天） |
-| `scheduleByDependencies` | 按依赖关系调整任务日期 |
-| `computeImpact` | 分析任务变更的影响和约束冲突 |
-| `checkCyclicDependency` | 检查循环依赖 |
-| `normalizeLinks` | 统一任务内依赖与独立依赖数据 |
-| `flattenTasks` | 将阶段树转换为可渲染行 |
-| `toDate`、`toDateTime`、`addDays`、`addHours`、`diffDays`、`diffHours`、`formatDate`、`formatDateTime` | 日期工具（`toDateTime`/`diffHours` 保留时间，用于小时级计算） |
-
-## 数据说明
-
-- `plan` 表示计划日期。
-- `actual` 表示实际日期和完成进度。
-- `summary` 表示阶段，`task` 表示普通任务，`milestone` 表示任务型里程碑。
-- Core 不负责绘制界面；需要现成 Vue 界面时请安装 `ct-gantt-vue`。
-
-完整类型、配置和示例请查看[项目文档](https://github.com/moonlight-219/ganttu#readme)。
+# ct-gantt-core
+
+框架无关的甘特图数据、布局、依赖排程和命令式引擎。该包不包含界面，可用于 Vue、React、原生 JavaScript、服务端计算或自定义渲染器。
+
+## 安装
+
+支持 npm / pnpm / yarn 三种包管理器，任选其一：
+
+```bash
+# npm
+npm install ct-gantt-core
+
+# pnpm
+pnpm add ct-gantt-core
+
+# yarn
+yarn add ct-gantt-core
+```
+
+`ct-gantt-core` 框架无关、无运行时依赖，Vue / React / 原生 JavaScript / 服务端环境均可直接使用。
+
+## 最小示例
+
+```ts
+import { GanttEngine, type GanttTask } from "ct-gantt-core"
+
+// 任务：type 区分 task / milestone / summary；
+// plan 是计划日期，actual 是实际日期与进度。
+const tasks: GanttTask[] = [
+  {
+    id: "task-1",
+    name: "需求分析",
+    type: "task",
+    plan: { start: "2026-07-01", end: "2026-07-05" },
+    actual: { start: "2026-07-01", end: "2026-07-06", progress: 60 }
+  }
+]
+
+// 创建引擎：持有任务、依赖与视口配置，负责全部数据计算。
+const engine = new GanttEngine({
+  tasks,
+  config: { viewMode: "day", columnWidth: 30 }
+})
+
+// 计算布局：ok 为 true 时 data 含每个任务条的像素位置与尺寸。
+const layout = engine.getLayout()
+if (layout.ok) {
+  console.log(layout.data)
+}
+
+engine.setTask("task-1", { progress: 80 }) // 命令式更新任务并触发重算
+engine.destroy() // 释放引擎内部资源
+```
+
+## 依赖排程
+
+```ts
+import { scheduleByDependencies, type GanttLink } from "ct-gantt-core"
+
+// 依赖：FS 表示 design 完成后 dev 才能开始。
+const links: GanttLink[] = [
+  { id: "design-to-dev", sourceId: "design", targetId: "dev", type: "FS" }
+]
+
+// 按依赖推算任务日期；ok 为 false 时 error 含原因（如循环依赖）。
+const result = scheduleByDependencies(tasks, links)
+if (result.ok) {
+  console.log(result.data)
+}
+```
+
+支持 `FS`、`SS`、`FF`、`SF` 四种依赖类型，以及自然日或工作日间隔。
+
+## 主要导出
+
+| API | 用途 |
+| --- | --- |
+| `GanttEngine` | 管理任务、依赖、折叠、预览、布局和视口命令 |
+| `computeLayout` | 计算任务条位置和尺寸 |
+| `computeTimeScale` | 计算时间刻度（day/week/month/quarter/year） |
+| `computeHourScale` | 计算小时级时间刻度（每天 24 个小时列，顶行日期 + 底部整点小时） |
+| `computeResourceLayout` | 资源视图布局：资源行 + 占用色条（支持 day/hour 粒度与车道堆叠） |
+| `resolveUsageTimes` | 将资源占用解析为布局用起止时间（hour 粒度下纯日期占用含结束日整天） |
+| `scheduleByDependencies` | 按依赖关系调整任务日期 |
+| `computeImpact` | 分析任务变更的影响和约束冲突 |
+| `checkCyclicDependency` | 检查循环依赖 |
+| `normalizeLinks` | 统一任务内依赖与独立依赖数据 |
+| `flattenTasks` | 将阶段树转换为可渲染行 |
+| `toDate`、`toDateTime`、`addDays`、`addHours`、`diffDays`、`diffHours`、`formatDate`、`formatDateTime` | 日期工具（`toDateTime`/`diffHours` 保留时间，用于小时级计算） |
+
+## 数据说明
+
+- `plan` 表示计划日期。
+- `actual` 表示实际日期和完成进度。
+- `summary` 表示阶段，`task` 表示普通任务，`milestone` 表示任务型里程碑。
+- Core 不负责绘制界面；需要现成 Vue 界面时请安装 `ct-gantt-vue`。
+
+完整类型、配置和示例请查看[项目文档](https://github.com/moonlight-219/ganttu#readme)。

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   addHours: () => addHours,
   addPlannedDuration: () => addPlannedDuration,
   alignPlannedDate: () => alignPlannedDate,
+  calendarIncludesWeekends: () => calendarIncludesWeekends,
   checkCyclicDependency: () => checkCyclicDependency,
   computeHourScale: () => computeHourScale,
   computeImpact: () => computeImpact,
@@ -58,6 +59,7 @@ __export(index_exports, {
   mergeTaskPatch: () => mergeTaskPatch,
   normalizeLinks: () => normalizeLinks,
   plannedDurationBetween: () => plannedDurationBetween,
+  resolveColumnWidth: () => resolveColumnWidth,
   resolveGanttConfig: () => resolveGanttConfig,
   resolveResourceColor: () => resolveResourceColor,
   resolveUsageColor: () => resolveUsageColor,
@@ -109,8 +111,13 @@ var DEFAULT_WORKLOAD_COLORS = {
 var RESOURCE_COLOR_PALETTE = [DEFAULT_RESOURCE_COLORS.booking];
 var RESOURCE_EDITOR_COLOR_OPTIONS = [
   "#409eff",
-  "#79bbff",
-  "#909399"
+  "#66b1ff",
+  "#67c23a",
+  "#e6a23c",
+  "#f56c6c",
+  "#909399",
+  "#9b87c4",
+  "#36cfc9"
 ];
 var EDITOR_COLOR_OPTIONS = [
   "#409eff",
@@ -137,6 +144,7 @@ var defaultConfig = {
   showPlanBar: true,
   showActualBar: true,
   showTimelineWhenEmpty: false,
+  highlightWeekend: true,
   builtInTaskEditor: false,
   builtInMarkerEditor: true,
   editablePlan: false,
@@ -147,6 +155,7 @@ var defaultConfig = {
   taskColors: { ...DEFAULT_TASK_COLORS },
   resourceUsageColors: { ...DEFAULT_RESOURCE_COLORS },
   workloadColors: { ...DEFAULT_WORKLOAD_COLORS },
+  workloadDefaultCapacity: 8,
   timeUnit: "day",
   hourWidth: 12,
   autoSchedule: true,
@@ -388,11 +397,14 @@ function alignPlannedDate(date, calendarId = "standard", direction = 1) {
   }
   return current;
 }
+function calendarIncludesWeekends(calendarId) {
+  return calendarId === "delivery";
+}
 function plannedDurationBetween(start, end, calendarId = "standard") {
   const first = toDate(start);
   const last = toDate(end);
   if (last.getTime() < first.getTime()) return 0;
-  if (calendarId === "delivery") return inclusiveDays(first, last);
+  if (calendarIncludesWeekends(calendarId)) return inclusiveDays(first, last);
   let duration = 0;
   for (let current = first; current <= last; current = addDays(current, 1)) {
     const day = current.getDay();
@@ -564,6 +576,9 @@ function mergeGanttConfig(base, patch = {}) {
 function resolveGanttConfig(patch = {}) {
   return mergeGanttConfig(defaultConfig, patch);
 }
+function resolveColumnWidth(config, viewMode = config.viewMode ?? defaultConfig.viewMode) {
+  return config.columnWidths?.[viewMode] ?? config.columnWidth ?? defaultConfig.columnWidth;
+}
 
 // src/engines/scheduling.ts
 function scheduleByDependencies(tasks, links) {
@@ -856,7 +871,7 @@ function computeResourceLayout(resources, usages, config, viewport) {
   const mergedConfig = resolveGanttConfig(config);
   const timeUnit = mergedConfig.timeUnit ?? "day";
   const hourMode = timeUnit === "hour";
-  const hourW = mergedConfig.hourWidth ?? 12;
+  const hourW = mergedConfig.hourWidth ?? mergedConfig.columnWidth ?? 12;
   for (const usage of usages) {
     const { start, end } = resolveUsageTimes(usage, timeUnit);
     if (!isValidDate(start) || !isValidDate(end)) {
@@ -976,17 +991,38 @@ function isLaneFree(laneEnd, start, hourMode) {
 }
 
 // src/engines/computeWorkload.ts
-function computeWorkload(tasks, people, departments = [], range) {
+function computeWorkload(tasks, people, departments = [], range, groupBy, defaultCapacityPerDay, includeIdle = false, includeWeekends, dateSource = "plan") {
   const dated = range ?? inferRange(tasks);
   if (!dated) return { dates: [], departments: [], ungrouped: [] };
   const dates = datesBetween(dated.start, dated.end);
   const dateIndex = new Map(dates.map((date, index) => [date, index]));
-  const rows = new Map(people.map((person) => [person.id, createPerson(person, dates)]));
+  const parentIds = /* @__PURE__ */ new Set();
   for (const task of tasks) {
-    if (task.type === "summary" || task.type === "milestone") continue;
+    if (task.parentId) parentIds.add(task.parentId);
+  }
+  const isCountable = (task) => task.type === "task" || task.type === "summary" && !parentIds.has(task.id);
+  const activeIds = /* @__PURE__ */ new Set();
+  for (const task of tasks) {
+    if (!isCountable(task)) continue;
+    for (const id of task.resources ?? []) activeIds.add(id);
+  }
+  const candidates = mergePeopleWithTaskResources(people, tasks);
+  const members = includeIdle ? candidates : candidates.filter((person) => activeIds.has(person.id));
+  const rows = new Map(members.map((person) => [person.id, createPerson(person, dates, defaultCapacityPerDay)]));
+  const tasksByPerson = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    if (!isCountable(task)) continue;
+    for (const id of task.resources ?? []) {
+      const list = tasksByPerson.get(id);
+      if (list) list.push(task);
+      else tasksByPerson.set(id, [task]);
+    }
+  }
+  for (const task of tasks) {
+    if (!isCountable(task)) continue;
     const ids = task.resources ?? [];
     if (!ids.length) continue;
-    const values = task.dailyWorkloads ?? averageTaskWorkload(task);
+    const values = task.dailyWorkloads ?? averageTaskWorkload(task, includeWeekends, dateSource);
     for (const personId of ids) {
       const row = rows.get(personId);
       if (!row) continue;
@@ -999,19 +1035,44 @@ function computeWorkload(tasks, people, departments = [], range) {
   for (const row of rows.values()) finalize(row);
   const grouped = /* @__PURE__ */ new Map();
   const ungrouped = [];
+  const keyOf = groupBy ?? ((person) => person.departmentId);
   for (const row of rows.values()) {
-    if (row.person.departmentId) {
-      const members = grouped.get(row.person.departmentId);
-      if (members) members.push(row);
-      else grouped.set(row.person.departmentId, [row]);
+    const key = keyOf(row.person, members, tasksByPerson.get(row.person.id) ?? []);
+    if (key) {
+      const list = grouped.get(key);
+      if (list) list.push(row);
+      else grouped.set(key, [row]);
     } else {
       ungrouped.push(row);
     }
   }
   const departmentMap = new Map(departments.map((item) => [item.id, item]));
-  const result = [...grouped].map(([id, members]) => aggregateDepartment(departmentMap.get(id) ?? { id, name: id }, members, dates));
+  const result = [...grouped].map(([id, list]) => aggregateDepartment(departmentMap.get(id) ?? { id, name: id }, list, dates));
   return { dates, departments: result, ungrouped };
 }
+function derivePeople(tasks) {
+  const map = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    for (const id of task.resources ?? []) {
+      if (!map.has(id)) map.set(id, { id, name: id });
+    }
+  }
+  return [...map.values()];
+}
+function mergePeopleWithTaskResources(people, tasks) {
+  const list = people?.length ? [...people] : derivePeople(tasks);
+  const known = new Set(list.map((person) => person.id));
+  for (const task of tasks) {
+    if (task.type === "summary" || task.type === "milestone") continue;
+    for (const id of task.resources ?? []) {
+      if (!known.has(id)) {
+        known.add(id);
+        list.push({ id, name: id });
+      }
+    }
+  }
+  return list;
+}
 function inferRange(tasks) {
   if (!tasks.length) return void 0;
   const extent = dateExtent(tasks.flatMap((task) => [toDate(task.plan.start), toDate(task.plan.end)]));
@@ -1022,18 +1083,22 @@ function datesBetween(start, end) {
   for (let date = toDate(start); date <= toDate(end); date = addDays(date, 1)) values.push(formatDate(date));
   return values;
 }
-function averageTaskWorkload(task) {
-  const total = task.workload ?? (task.duration ?? inclusiveDays(task.plan.start, task.plan.end)) * 8;
-  const allDates = datesBetween(task.plan.start, task.plan.end);
-  const dates = task.calendarId === "delivery" ? allDates : allDates.filter((date) => {
+function averageTaskWorkload(task, includeWeekends, dateSource = "plan") {
+  const sourceStart = dateSource === "actual" ? task.actual.start : task.plan.start;
+  const sourceEnd = dateSource === "actual" ? task.actual.end : task.plan.end;
+  const allDates = datesBetween(sourceStart, sourceEnd);
+  const workdays = allDates.filter((date) => {
     const day = toDate(date).getDay();
     return day !== 0 && day !== 6;
   });
+  const withWeekends = task.includeWeekends ?? includeWeekends ?? calendarIncludesWeekends(task.calendarId);
+  const dates = withWeekends ? allDates : workdays;
+  const total = task.workload ?? dates.length * 8;
   const hours = dates.length ? total / dates.length : 0;
   return Object.fromEntries(dates.map((date) => [date, hours]));
 }
-function createPerson(person, dates) {
-  return { person, days: dates.map((date) => ({ date, hours: 0, capacity: person.capacityPerDay ?? 8 })), workload: 0, capacity: 0, utilization: 0, progress: 0 };
+function createPerson(person, dates, defaultCapacityPerDay) {
+  return { person, days: dates.map((date) => ({ date, hours: 0, capacity: person.capacityPerDay ?? defaultCapacityPerDay ?? 8 })), workload: 0, capacity: 0, utilization: 0, progress: 0 };
 }
 function finalize(row) {
   row.workload = row.days.reduce((sum, day) => sum + day.hours, 0);
@@ -1076,15 +1141,25 @@ function mergeTaskPatch(task, patch) {
   };
 }
 var GanttEngine = class {
+  /** 任务列表（内部以浅拷贝存储，避免外部引用篡改）。 */
   tasks;
+  /** 链路列表（内部以浅拷贝存储）。 */
   links;
+  /** 合并后的完整配置。 */
   config;
+  /** 滚动容器元素；可为 null（纯计算场景）。 */
   container;
+  /** 当前折叠的任务 id 集合。 */
   collapsedIds;
+  /** 拖拽预览状态；null 表示无预览。 */
   dragPreview = null;
+  /** 里程碑标记列表。 */
   markers;
+  /** 事件名 → 监听器集合。 */
   listeners;
+  /** 是否已销毁。 */
   destroyed = false;
+  /** 构造引擎：初始化数据、合并配置，并异步发出 ready 事件。 */
   constructor(options = {}) {
     this.tasks = options.tasks ? options.tasks.map((task) => ({ ...task })) : [];
     this.links = options.links ? options.links.map((link) => ({ ...link })) : [];
@@ -1095,40 +1170,50 @@ var GanttEngine = class {
     this.listeners = /* @__PURE__ */ new Map();
     queueMicrotask(() => this.emit("ready"));
   }
-  // ── 状态查询 ──
+  // ── 状态查询（均返回副本，避免外部直接篡改内部状态） ──
+  /** 获取全部任务的浅拷贝数组。 */
   getTasks() {
     return this.tasks.map((task) => ({ ...task }));
   }
+  /** 获取全部链路的浅拷贝数组。 */
   getLinks() {
     return this.links.map((link) => ({ ...link }));
   }
+  /** 获取全部里程碑标记的浅拷贝数组。 */
   getMarkers() {
     return this.markers.map((marker) => ({ ...marker }));
   }
+  /** 获取当前配置的浅拷贝。 */
   getConfig() {
     return { ...this.config };
   }
+  /** 按 id 查询单个任务，不存在时返回 undefined。 */
   getTask(id) {
     const task = this.tasks.find((item) => item.id === id);
     return task ? { ...task } : void 0;
   }
+  /** 获取当前折叠的任务 id 列表。 */
   getCollapsedIds() {
     return Array.from(this.collapsedIds);
   }
+  /** 引擎是否已被销毁（destroy 之后为 true）。 */
   isDestroyed() {
     return this.destroyed;
   }
   // ── 命令式变更（均触发对应事件） ──
+  /** 整体替换任务列表，并触发 taskschange 事件。 */
   setTasks(tasks) {
     this.assertNotDestroyed();
     this.tasks = tasks.map((task) => ({ ...task }));
     this.emit("taskschange", this.tasks);
   }
+  /** 整体替换链路列表，并触发 linkschange 事件。 */
   setLinks(links) {
     this.assertNotDestroyed();
     this.links = links.map((link) => ({ ...link }));
     this.emit("linkschange", this.links);
   }
+  /** 整体替换里程碑标记列表，并触发 markerschange 事件。 */
   setMarkers(markers) {
     this.assertNotDestroyed();
     this.markers = markers.map((marker) => ({ ...marker }));
@@ -1140,6 +1225,7 @@ var GanttEngine = class {
     this.config = mergeGanttConfig(this.config, patch);
     this.emit("configchange", this.getConfig());
   }
+  /** 以合并方式设置配置，等价于 setConfig(mergeConfig(patch)) 的便捷封装。 */
   setConfig(config) {
     this.mergeConfig(config);
   }
@@ -1154,11 +1240,13 @@ var GanttEngine = class {
     this.tasks = this.tasks.map((task) => task.id === id ? updated : task);
     this.emit("taskchange", id, patch, { ...updated });
   }
+  /** 追加一个新任务，并触发 taskcreate 事件。 */
   addTask(task) {
     this.assertNotDestroyed();
     this.tasks = [...this.tasks, { ...task }];
     this.emit("taskcreate", { ...task });
   }
+  /** 按 id 删除任务（不存在时静默忽略），并触发 taskdelete 事件。 */
   removeTask(id) {
     this.assertNotDestroyed();
     const removed = this.tasks.find((task) => task.id === id);
@@ -1167,12 +1255,14 @@ var GanttEngine = class {
     this.collapsedIds.delete(id);
     this.emit("taskdelete", id);
   }
+  /** 折叠/展开单个任务，并触发 collapsechange 事件。 */
   collapse(id, collapsed = true) {
     this.assertNotDestroyed();
     if (collapsed) this.collapsedIds.add(id);
     else this.collapsedIds.delete(id);
     this.emit("collapsechange", this.getCollapsedIds());
   }
+  /** 切换单个任务的折叠状态。 */
   toggleCollapse(id) {
     this.collapse(id, !this.collapsedIds.has(id));
   }
@@ -1191,6 +1281,7 @@ var GanttEngine = class {
     this.emit("collapsechange", this.getCollapsedIds());
   }
   // ── 拖拽预览（交互态源；组件写入迁移到 engine，dateRange 可据此扩展） ──
+  /** 记录一次拖拽预览状态（含受影响的联动任务），并触发 previewchange 事件。 */
   setPreview(preview) {
     this.assertNotDestroyed();
     this.dragPreview = {
@@ -1200,6 +1291,7 @@ var GanttEngine = class {
     };
     this.emit("previewchange", this.getPreview());
   }
+  /** 清空拖拽预览（无预览时忽略），并触发 previewchange 事件。 */
   clearPreview() {
     if (!this.dragPreview) {
       return;
@@ -1207,6 +1299,7 @@ var GanttEngine = class {
     this.dragPreview = null;
     this.emit("previewchange", null);
   }
+  /** 获取当前拖拽预览的副本，无预览时返回 null。 */
   getPreview() {
     if (!this.dragPreview) {
       return null;
@@ -1260,6 +1353,7 @@ var GanttEngine = class {
     const extent = dateExtent(dates);
     return extent ?? { start: dates[0], end: dates[0] };
   }
+  /** 计算时间刻度（委托给 computeTimeScale 纯函数）。 */
   getTimeScale() {
     const range = this.getDateRange();
     return computeTimeScale(
@@ -1270,6 +1364,7 @@ var GanttEngine = class {
       this.config.firstDayOfWeek
     );
   }
+  /** 计算任务行布局（委托给 computeLayout 纯函数）。 */
   getLayout() {
     return computeLayout(
       this.tasks,
@@ -1278,20 +1373,25 @@ var GanttEngine = class {
       this.collapsedIds
     );
   }
+  /** 计算扁平化任务列表（委托给 flattenTasks 纯函数）。 */
   getFlatTasks() {
     return flattenTasks(this.tasks, this.collapsedIds);
   }
+  /** timeline 总宽度（所有刻度宽度之和）。 */
   getTotalWidth() {
     return this.getTimeScale().reduce((sum, tick) => sum + tick.width, 0);
   }
+  /** 整体高度（表头 + 行数 × 行高）。 */
   getTotalHeight() {
     const rows = this.getFlatTasks().length;
     return this.config.headerHeight + rows * this.config.rowHeight;
   }
   // ── 视口命令（需要 container） ──
+  /** 当前横向滚动位置（无容器时为 0）。 */
   getScrollLeft() {
     return this.container?.scrollLeft ?? 0;
   }
+  /** 设置横向滚动位置（自动夹取到 [0, maxScrollLeft]）。 */
   setScrollLeft(px) {
     if (!this.container) return;
     const max = Math.max(0, this.container.scrollWidth - this.container.clientWidth);
@@ -1307,9 +1407,11 @@ var GanttEngine = class {
       this.container.scrollLeft = max;
     }
   }
+  /** 当前纵向滚动位置（无容器时为 0）。 */
   getScrollTop() {
     return this.container?.scrollTop ?? 0;
   }
+  /** 设置纵向滚动位置（自动夹取到 [0, maxScrollTop]）。 */
   setScrollTop(px) {
     if (!this.container) return;
     const max = Math.max(0, this.container.scrollHeight - this.container.clientHeight);
@@ -1324,15 +1426,18 @@ var GanttEngine = class {
     const left = tick ? tick.left : diffDays(this.getDateRange().start, target) * this.config.columnWidth;
     this.setScrollLeft(left);
   }
+  /** 滚动到某个任务的所在列（按布局 left 定位）。 */
   scrollToTask(id) {
     const layout = this.getLayout();
     if (!layout.ok) return;
     const item = layout.data.find((row) => row.taskId === id);
     if (item) this.setScrollLeft(item.left);
   }
+  /** 滚动到最左侧。 */
   scrollToStart() {
     this.setScrollLeft(0);
   }
+  /** 滚动到最右侧（按 timeline 总宽度）。 */
   scrollToEnd() {
     if (!this.container) return;
     this.setScrollLeft(this.getTotalWidth());
@@ -1351,10 +1456,12 @@ var GanttEngine = class {
     const target = this.container.clientWidth / span;
     this.mergeConfig({ columnWidth: this.clampColumnWidth(target) });
   }
+  /** 把列宽限制到 [4, 400] 并取整。 */
   clampColumnWidth(value) {
     return Math.max(4, Math.min(400, Math.round(value)));
   }
   // ── 事件订阅 ──
+  /** 订阅事件，返回取消订阅函数（同一事件可多次订阅）。 */
   on(event, fn) {
     this.assertNotDestroyed();
     let set = this.listeners.get(event);
@@ -1371,6 +1478,7 @@ var GanttEngine = class {
       }
     };
   }
+  /** 订阅单次事件：触发一次后自动取消订阅，返回取消订阅函数。 */
   once(event, fn) {
     const off = this.on(event, (...args) => {
       off();
@@ -1378,6 +1486,7 @@ var GanttEngine = class {
     });
     return off;
   }
+  /** 取消订阅；不传 fn 时移除该事件的全部监听器。 */
   off(event, fn) {
     const set = this.listeners.get(event);
     if (!set) return;
@@ -1388,6 +1497,7 @@ var GanttEngine = class {
       this.listeners.delete(event);
     }
   }
+  /** 触发事件，逐个调用监听器；单个监听器抛错不影响其余监听器。 */
   emit(event, ...args) {
     const set = this.listeners.get(event);
     if (!set) return;
@@ -1402,6 +1512,7 @@ var GanttEngine = class {
     }
   }
   // ── 生命周期 ──
+  /** 销毁引擎：置位 destroyed、触发 destroy 事件并清空监听器与数据。 */
   destroy() {
     if (this.destroyed) return;
     this.destroyed = true;
@@ -1410,6 +1521,7 @@ var GanttEngine = class {
     this.tasks = [];
     this.links = [];
   }
+  /** 断言引擎未被销毁，否则抛出异常（防止对已销毁实例操作）。 */
   assertNotDestroyed() {
     if (this.destroyed) {
       throw new Error("GanttEngine: operation on destroyed instance");
@@ -1436,6 +1548,7 @@ function createGanttEngine(options = {}) {
   addHours,
   addPlannedDuration,
   alignPlannedDate,
+  calendarIncludesWeekends,
   checkCyclicDependency,
   computeHourScale,
   computeImpact,
@@ -1459,6 +1572,7 @@ function createGanttEngine(options = {}) {
   mergeTaskPatch,
   normalizeLinks,
   plannedDurationBetween,
+  resolveColumnWidth,
   resolveGanttConfig,
   resolveResourceColor,
   resolveUsageColor,