@toclocoinc/lattice-grid 1.68.0 → 1.68.2

package/modules/gantt.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, gantt module type declarations
+ * Lattice Grid 1.68.2, gantt module type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -25,21 +25,83 @@ export type GanttCalendar =
  * view's grid panel.
  */
 export interface GanttTask {
+  /**
+   * The task's identity, used by dependencies, edits and `rows.apply`. Stringified; a
+   * duplicate id fails the schedule with `duplicate-id`.
+   */
   id: string | number;
+  /** The task's label in the table and on its bar. Defaults to the id. */
   name?: string;
+  /**
+   * Where the task is placed — a day-number, an ISO date or a `Date`. It is a floor, not
+   * a pin: the forward pass never starts the task earlier, but a predecessor may push it
+   * later. Use a `constraint` to pin it.
+   */
   start?: number | string | Date;
+  /**
+   * The task's finish, in the same forms as `start`. Given with `start` and no
+   * `duration`, the duration becomes `end − start`.
+   */
   end?: number | string | Date;
+  /**
+   * How long the task takes, in working days (the plan's time unit). Negative fails the
+   * schedule with `bad-duration`; a leaf with no duration and no start/end pair is an
+   * error, while a summary's is ignored because its window comes from its children.
+   */
   duration?: number;
+  /**
+   * Progress, 0-100, drawn as the filled part of the bar and used as the earned-value
+   * multiplier. A summary's is the duration-weighted mean of its descendant leaves;
+   * anything unparseable reads as null.
+   */
   percentComplete?: number;
+  /**
+   * Marks a zero-duration point: the task is scheduled as an instant (start equals
+   * finish) and drawn as a diamond. `duration: 0` does the same.
+   */
   milestone?: boolean;
+  /**
+   * The id of the summary task this one sits under. A summary is never scheduled in its
+   * own right — its window, progress and criticality are derived from its children — and
+   * a parent chain that loops fails with `parent-cycle`.
+   */
   parent?: string | number;
+  /**
+   * The planned start the task is measured against, in the same forms as `start`. With a
+   * baseline the schedule reports `startVariance` (actual − planned; positive is a slip).
+   */
   baselineStart?: number | string | Date;
+  /**
+   * The planned finish. With both baseline dates the schedule reports `finishVariance`
+   * and `durationVariance` too.
+   */
   baselineEnd?: number | string | Date;
+  /** The planned window as one object, read when `baselineStart`/`baselineEnd` are absent. */
   baseline?: { start?: number | string | Date; end?: number | string | Date };
+  /**
+   * Pins or pulls the task: must-start-on and must-finish-on place it on
+   * `constraintDate`, as-late-as-possible pulls it into its late window, consuming its
+   * float. A constraint date earlier than the predecessors allow is reported in
+   * `schedule.conflicts` and the feasible date is used instead.
+   */
   constraint?: GanttConstraintType;
+  /**
+   * The date the constraint pins to — a day-number, ISO date or `Date`. Unused by
+   * as-late-as-possible.
+   */
   constraintDate?: number | string | Date;
+  /**
+   * Who is booked on the task: one name or a list. Each name is a full-time booking
+   * (units 1) for resource load, over-allocation and the split view's avatars. Ignored
+   * when `assignments` is present.
+   */
   assignee?: string | string[];
+  /** An alternative spelling of `assignee`, read when that is absent. */
   assignees?: string[];
+  /**
+   * A third spelling of `assignee`, read when neither `assignee` nor `assignees` is
+   * present.
+   */
   owner?: string;
   /**
    * Explicit resource assignments with fractional units:
@@ -101,55 +163,144 @@ export type GanttResourceSpec =
  * field warns; the explicit field wins.
  */
 export interface GanttDependency {
+  /**
+   * The predecessor task's id. A link naming a summary is expanded to its descendant
+   * leaves before scheduling.
+   */
   from: string | number;
+  /** The successor task's id. */
   to: string | number;
+  /**
+   * Which ends the link ties together — finish-to-start (the default), start-to-start,
+   * finish-to-finish or start-to-finish — optionally with the MS Project lag shorthand,
+   * `'FS+2'` or `'SS-1'`. It is normalised on the way in, so `gantt.dependencies` always
+   * reads back as `{ type, lag }`.
+   */
   type?: GanttLinkType | `${GanttLinkType}${'+' | '-'}${number}`;
+  /**
+   * A signed offset on the link in working days; a negative value is a lead. Given
+   * alongside a shorthand lag in `type`, this field wins and the mismatch is warned
+   * about.
+   */
   lag?: number;
 }
 
 /** The computed CPM values for one task (a leaf is scheduled, a summary derived). */
 interface GanttScheduledTask {
+  /** The task's id, as a string. */
   id: string;
+  /** The task's name, defaulting to its id. */
   name: string;
+  /** The task's length in working days. A summary's is its derived window, `ef − es`. */
   duration: number;
+  /**
+   * Early start: the earliest day the task can begin once every predecessor and its own
+   * placement floor are honoured.
+   */
   es: number;
+  /**
+   * Early finish, `es + duration` (mapped back to calendar days when a working-time
+   * calendar is in use).
+   */
   ef: number;
+  /**
+   * Late start: the latest the task can begin without pushing the project finish (or the
+   * deadline) out.
+   */
   ls: number;
+  /**
+   * Late finish, `ls + duration`. A task pinned by a constraint has `lf` equal to its
+   * `ef`, so it has no float.
+   */
   lf: number;
+  /**
+   * Slack in working days, `ls − es`. Zero means critical; a deadline earlier than the
+   * natural finish drives it negative, which is the at-risk signal.
+   */
   totalFloat: number;
+  /**
+   * True when the total float is zero or negative. A summary is critical when any child
+   * is; an as-late-as-possible task is always marked critical.
+   */
   critical: boolean;
+  /**
+   * The task's progress, or null when it states none. A summary's is the
+   * duration-weighted mean of its descendant leaves, and null when every one of them is a
+   * milestone.
+   */
   percentComplete: number | null;
+  /** The id of this task's summary, or null at the top level. */
   parent: string | null;
+  /** True when the task has children, and so was derived from them rather than scheduled. */
   isSummary: boolean;
+  /** True when the task's duration is zero — a point in the plan. */
   isMilestone: boolean;
+  /** A summary's direct children, by id, in input order. Empty for a leaf. */
   children: string[];
   /** The planned (baseline) window, present only when the task carries a baseline. */
   baselineStart?: number | null;
+  /** The planned finish day-number, or null when only a baseline start was given. */
   baselineEnd?: number | null;
   /** Variance vs the baseline (actual − planned, day-numbers); a positive value is a slip. */
   startVariance?: number | null;
+  /**
+   * `ef − baselineEnd` in days; positive means finishing later than planned. Null without
+   * a baseline finish.
+   */
   finishVariance?: number | null;
+  /**
+   * How much longer the task runs than its baseline window, in days. Null unless both
+   * baseline dates were given.
+   */
   durationVariance?: number | null;
 }
 
 /** An unhonourable scheduling constraint, reported rather than obeyed. */
 interface GanttConflict {
+  /** The task whose constraint could not be honoured. */
   id: string;
+  /** The constraint that was refused, as its normalised code (`MSO` or `MFO`). */
   type: string;
+  /** The date the constraint asked for, as a day-number, or null when it named none. */
   at: number | null;
+  /**
+   * The earliest start the predecessors actually allow — the day the engine used instead.
+   * It never places a task before its predecessors.
+   */
   earliestFeasible: number;
 }
 
 /** A CPM schedule result: per-task dates/float and the critical path, or an error. */
 interface GanttSchedule {
+  /**
+   * Whether the schedule computed. False leaves every other field absent except `error`,
+   * and the controller keeps its previous schedule.
+   */
   ok: boolean;
-  error?: { code: string; message: string; cycle?: string[] };
+  /** Why the schedule was refused — the same object the `error` event carries. */
+  error?: GanttScheduleError;
+  /** Every task's computed values, keyed by id — leaves scheduled, summaries derived. */
   tasks?: Map<string, GanttScheduledTask>;
+  /** Every task id in input order, which is the order a table or WBS tree walks. */
   order?: string[];
+  /** The ids of the leaf tasks with no float, in input order. */
   critical?: string[];
+  /**
+   * Each zero-float chain through the network as its own list of ids, so a plan with
+   * several critical routes shows all of them.
+   */
   criticalPaths?: string[][];
+  /**
+   * The day the plan is anchored to — the `projectStart` option, or the calendar's first
+   * working day when one is set.
+   */
   projectStart?: number;
+  /** The latest early finish across every task, as a calendar day-number. */
   projectFinish?: number;
+  /**
+   * `projectFinish − projectStart` in days — calendar days when a working-time calendar
+   * stretched the plan, not the sum of the durations.
+   */
   projectDuration?: number;
   /** Constraints a predecessor made infeasible (empty when all are satisfied). */
   conflicts?: GanttConflict[];
@@ -163,46 +314,105 @@ interface GanttSchedule {
 
 /** One contiguous load segment for a resource: how many units are booked over a span. */
 interface GanttResourceSegment {
+  /** The day the segment begins (inclusive), as a calendar day-number. */
   start: number;
+  /**
+   * The day the segment ends (exclusive). A task that finishes as another starts does not
+   * double-count the boundary.
+   */
   end: number;
+  /**
+   * The units booked across the whole segment — the sum of the covering tasks' assignment
+   * units, where 1 is one full-time booking.
+   */
   load: number;
+  /** The tasks active during the segment, which is what makes a heavy stretch explainable. */
   taskIds: string[];
 }
 
 /** A resource booked beyond its capacity across concurrent tasks. */
 interface GanttOverAllocation {
+  /** The over-booked resource's name. */
   resource: string;
+  /**
+   * The resource's capacity in units — from the `resources` option, or `defaultCapacity`
+   * (1) when it names none.
+   */
   capacity: number;
+  /** The day the over-allocation begins, as a calendar day-number. */
   start: number;
+  /** The day it ends (exclusive). */
   end: number;
+  /**
+   * The units booked over that stretch — strictly greater than `capacity`, which is what
+   * makes it an over-allocation.
+   */
   load: number;
+  /** The tasks competing for the resource over that stretch. */
   taskIds: string[];
 }
 
 /** The per-resource load and the over-allocations across a schedule. */
 interface GanttResourceLoad {
+  /**
+   * Whether the load could be computed. False — with empty lists — when there is no
+   * successful schedule to read.
+   */
   ok: boolean;
+  /**
+   * One entry per resource that anything is booked on, sorted by name, each with its
+   * capacity, peak load and load segments. A resource named only in the capacities, with
+   * no booking, does not appear.
+   */
   resources: Array<{ resource: string; capacity: number; peak: number; segments: GanttResourceSegment[] }>;
+  /**
+   * Every stretch where a resource is booked beyond its capacity, earliest first. Empty
+   * when the plan fits.
+   */
   overAllocations: GanttOverAllocation[];
+  /** The same entries as `resources`, keyed by resource name for a direct lookup. */
   byResource: Map<string, { capacity: number; peak: number; segments: GanttResourceSegment[] }>;
 }
 
 /** The result of resource leveling: the shifted tasks and what moved. */
 interface GanttLevelResult {
+  /**
+   * Whether leveling ran. False only when the plan would not schedule, in which case
+   * `error` says why.
+   */
   ok: boolean;
+  /**
+   * Whether every over-allocation was cleared. False when only pinned tasks were left to
+   * move, or the iteration cap was hit — the partial result is still returned.
+   */
   resolved?: boolean;
+  /**
+   * The tasks with their new starts. These are copies; the controller adopts them unless
+   * the call was a dry run.
+   */
   tasks?: GanttTask[];
+  /** The schedule computed from the levelled tasks. */
   schedule?: GanttSchedule;
+  /**
+   * What actually moved: the task, its start before leveling, its start after, and the
+   * delay in days. Unmoved tasks are not listed.
+   */
   moves?: Array<{ id: string; from: number; to: number; delay: number }>;
+  /** The over-allocations leveling could not clear. Absent when it resolved everything. */
   remaining?: GanttOverAllocation[];
+  /** Why the plan would not schedule — the same codes `GanttSchedule.error` uses. */
   error?: { code: string; message: string };
 }
 
 /** A placement violation flagged by `findViolations`. */
 interface GanttViolation {
+  /** The task placed earlier than its predecessors allow. */
   id: string;
+  /** Where the plan puts the task — the `start` on the raw task, as a day-number. */
   placedStart: number;
+  /** The earliest start CPM allows, given the dependencies and the calendar. */
   earliestStart: number;
+  /** How many days early the placement is, `earliestStart − placedStart`. */
   by: number;
 }
 
@@ -227,12 +437,13 @@ export function findViolations(tasks: GanttTask[], schedule: GanttSchedule): Gan
 export function toISODate(day: number): string | null;
 
 /** Earned-value metrics for one task or the whole project. */
-interface GanttEarnedValueRow {
-  id: string;
-  name: string;
-  isSummary: boolean;
-  isMilestone: boolean;
-  percentComplete: number | null;
+/**
+ * The earned-value figures themselves, without the task they belong to.
+ *
+ * The project total is exactly this and no more, so it has its own type
+ * rather than claiming to be a row with five fields it has never carried.
+ */
+interface GanttEarnedValueTotals {
   /** Whether a baseline (not the fallback scheduled window) drove PV. */
   hasBaseline: boolean;
   /** Whether any actual cost fed AC (else AC/CV/CPI are null). */
@@ -255,9 +466,31 @@ interface GanttEarnedValueRow {
   cpi: number | null;
 }
 
+/** One task's earned-value figures. */
+interface GanttEarnedValueRow extends GanttEarnedValueTotals {
+  /** The task the row is for. */
+  id: string;
+  /** The task's name. */
+  name: string;
+  /** True for a summary row, whose figures are the sums of its descendant leaves. */
+  isSummary: boolean;
+  /** True for a zero-duration task. */
+  isMilestone: boolean;
+  /**
+   * The task's progress, reported exactly as the task states it, or null when it states
+   * none — which earns nothing. The earned-value multiplier clamps it to 0-100 first.
+   */
+  percentComplete: number | null;
+}
+
 /** The earned-value result at a status date. */
 interface GanttEarnedValue {
+  /**
+   * Whether the metrics could be computed. False when there is no successful schedule to
+   * measure against.
+   */
   ok: boolean;
+  /** Why the metrics were refused — `NO_SCHEDULE` when the plan has not scheduled. */
   error?: { code: string; message: string };
   /** The status date the metrics were evaluated at (day-number). */
   statusDate?: number;
@@ -265,8 +498,11 @@ interface GanttEarnedValue {
   byTask?: Map<string, GanttEarnedValueRow>;
   /** The same rows in schedule order. */
   rows?: GanttEarnedValueRow[];
-  /** The project total, rolled up as money sums of the leaves. */
-  project?: GanttEarnedValueRow;
+  /**
+   * The project total, rolled up as money sums of the leaves. The figures only:
+   * a total belongs to no task, so it carries no id, name or progress.
+   */
+  project?: GanttEarnedValueTotals;
 }
 
 /**
@@ -282,21 +518,294 @@ export function computeEarnedValue(
   options?: { statusDate?: number | string | Date; costField?: string; actualCostField?: string },
 ): GanttEarnedValue;
 
+/**
+ * Why a schedule was refused.
+ *
+ * The payload of the `error` event — the very object the failed
+ * {@link GanttSchedule} carries, handed straight to the handler.
+ */
+interface GanttScheduleError {
+  /**
+   * What was wrong: `cycle`, `duplicate-id`, `bad-duration`, `unknown-task`,
+   * `unknown-parent`, `parent-cycle`, `self-dependency`, `bad-link-type` or
+   * `dep-across-hierarchy`.
+   */
+  code: string;
+  /** The failure in one English sentence, naming the task or link it is about. */
+  message: string;
+  /** The ids that form the cycle, on a `cycle`. */
+  cycle?: string[];
+  /** The task the failure is about, where one task is to blame. */
+  id?: string;
+  /** A rejected dependency's predecessor, on `dep-across-hierarchy`. */
+  from?: string;
+  /** A rejected dependency's successor, on `dep-across-hierarchy`. */
+  to?: string;
+}
+
+/**
+ * What every cancellable Gantt event carries on top of its own context.
+ *
+ * The controller's bus mirrors the grid core's `emitBefore` contract exactly,
+ * so a host writes the same handler shape against a Gantt as against a grid: a
+ * handler refuses the action by calling `preventDefault(reason?)`, by returning
+ * `false`, or by throwing, and may be `async` — every thenable return is
+ * awaited before the decision, so a confirm dialog or a server check can hold
+ * the write. Veto wins. On a veto the matching `<action>:cancelled` fires with
+ * the reason and the model is untouched; an action re-validated after an await
+ * and no longer applicable is cancelled as `'stale'`.
+ *
+ * Only the user-initiated paths are gated. The live/router `rows.apply` path is
+ * remote truth and raises none of these.
+ */
+interface GanttBeforeEvent {
+  /** Which event this is — `beforeTaskMove`, `beforeTaskDelete` and the rest. */
+  type: string;
+  /** True once a handler has refused the action. */
+  defaultPrevented: boolean;
+  /** The reason given to `preventDefault`, or null while nothing has refused it. */
+  reason: string | null;
+  /** Refuse the action; the optional reason is carried on the `<action>:cancelled` event. */
+  preventDefault(reason?: string): void;
+}
+
+/**
+ * An edit about to be applied to one task: the payload of `beforeTaskEdit`,
+ * `beforeTaskMove`, `beforeTaskResize`, `beforeProgressChange` and
+ * `beforeMilestoneMove`.
+ *
+ * One payload for the five, because they are one choke point — `applyEdit`
+ * classifies the patch and names the event, so which of the five fires says
+ * what kind of edit it is and the context below says what the edit is.
+ */
+interface GanttTaskEditEvent extends GanttBeforeEvent {
+  /** The task being edited, by id. */
+  id: string;
+  /** The task as it stands before the edit, as a shallow copy. */
+  task: GanttTask;
+  /** The edit itself: only the fields it changes. */
+  patch: { id: string | number; start?: number; end?: number; duration?: number; percentComplete?: number; work?: unknown };
+  /** Always `user`: only the user-initiated path is gated. */
+  origin: string;
+  /** Where the task starts now, from the plan, or its computed early start when it holds no start. */
+  from?: number | string | Date;
+  /** Where the patch would move it to; absent unless the patch sets `start`. */
+  to?: number | string | Date;
+  /** The duration the patch asks for; absent unless the patch sets one. */
+  duration?: number;
+  /** The progress the patch asks for; present only on a `beforeProgressChange`. */
+  value?: number;
+  /** The progress before it; present only on a `beforeProgressChange`. */
+  oldValue?: number;
+}
+
+/**
+ * An edit that was refused: the payload of `taskEdit:cancelled`,
+ * `taskMove:cancelled`, `taskResize:cancelled`, `progressChange:cancelled` and
+ * `milestoneMove:cancelled`. The same context the before-event carried, plus
+ * the reason; a notification, so it carries no `preventDefault`.
+ */
+interface GanttTaskEditCancelledEvent {
+  /** The task that was not edited. */
+  id: string;
+  /** The task, unchanged. */
+  task: GanttTask;
+  /** The edit that was not applied. */
+  patch: { id: string | number; start?: number; end?: number; duration?: number; percentComplete?: number; work?: unknown };
+  /** Always `user`. */
+  origin: string;
+  /** Where the task starts, still. */
+  from?: number | string | Date;
+  /** Where it would have gone. */
+  to?: number | string | Date;
+  /** The duration that was asked for. */
+  duration?: number;
+  /** The progress that was asked for. */
+  value?: number;
+  /** The progress before it. */
+  oldValue?: number;
+  /** The reason given to `preventDefault`, `'prevented'` when none was, or `'stale'` when the task had gone by the time a handler settled. */
+  reason: string;
+}
+
+/**
+ * Links about to be created: the payload of `beforeDependencyCreate`. A pure
+ * removal or reorder adds no link and is not gated at all.
+ */
+interface GanttDependencyCreateEvent extends GanttBeforeEvent {
+  /** Only the links this call adds, normalised. */
+  added: GanttDependency[];
+  /** The whole list the call would leave behind. */
+  dependencies: GanttDependency[];
+  /** Always `user`. */
+  origin: string;
+}
+
+/**
+ * Links that were not created: the payload of `dependencyCreate:cancelled`. A
+ * notification, so it carries no `preventDefault`.
+ */
+interface GanttDependencyCreateCancelledEvent {
+  /** The links that were not added. */
+  added: GanttDependency[];
+  /** The list that was not adopted; the controller kept the one it had. */
+  dependencies: GanttDependency[];
+  /** Always `user`. */
+  origin: string;
+  /** The reason given to `preventDefault`, or `'prevented'` when none was. */
+  reason: string;
+}
+
+/** A task about to be deleted, with its incident links: the payload of `beforeTaskDelete`. */
+interface GanttTaskDeleteEvent extends GanttBeforeEvent {
+  /** The task being deleted, by id. */
+  id: string;
+  /** The task itself, as a shallow copy — the only chance a handler has to read it. */
+  task: GanttTask;
+  /** Always `user`: the live/router `rows.apply` remove is never gated. */
+  origin: string;
+}
+
+/**
+ * A task that was not deleted: the payload of `taskDelete:cancelled`. A
+ * notification, so it carries no `preventDefault`.
+ */
+interface GanttTaskDeleteCancelledEvent {
+  /** The task that stayed. */
+  id: string;
+  /** The task itself. */
+  task: GanttTask;
+  /** Always `user`. */
+  origin: string;
+  /** The reason given to `preventDefault`, `'prevented'` when none was, or `'stale'`. */
+  reason: string;
+}
+
+/**
+ * The events a Gantt controller raises.
+ *
+ * The controller's own, not a grid's: `grid.on` takes {@link EventName} and
+ * knows nothing about these, and a grid-bound Gantt follows the grid's events
+ * itself rather than re-publishing them. `on()` takes a name and a listener and
+ * warns about nothing, so a misspelt name is a subscription that never fires.
+ *
+ * The seven `before…` events are cancellable ({@link GanttBeforeEvent}); each
+ * has a matching `<action>:cancelled` that fires when a handler refuses,
+ * carrying the same context plus the reason. `schedule` and `error` are the
+ * recompute's own pair and are raised on every recompute, whatever caused it.
+ */
+type GanttEventName =
+  /** A recompute succeeded; the payload is the new schedule, resource load and over-allocations included. */
+  | 'schedule'
+  /** A recompute failed; the previous schedule is kept and the payload says what was wrong. */
+  | 'error'
+  /** A task edit that is not a move, a resize or a progress change is about to be applied; cancellable. */
+  | 'beforeTaskEdit'
+  /** A task is about to be moved — the patch sets `start` or `end`; cancellable. */
+  | 'beforeTaskMove'
+  /** A task is about to be resized — the patch sets `duration`; cancellable. */
+  | 'beforeTaskResize'
+  /** A task's progress is about to change — the patch sets `percentComplete`; cancellable. */
+  | 'beforeProgressChange'
+  /** A milestone is about to be moved — a move patch on a zero-length task; cancellable. */
+  | 'beforeMilestoneMove'
+  /** One or more dependency links are about to be created; cancellable. */
+  | 'beforeDependencyCreate'
+  /** A task is about to be deleted, along with every link touching it; cancellable. */
+  | 'beforeTaskDelete'
+  /** A `beforeTaskEdit` handler refused the edit. */
+  | 'taskEdit:cancelled'
+  /** A `beforeTaskMove` handler refused the move. */
+  | 'taskMove:cancelled'
+  /** A `beforeTaskResize` handler refused the resize. */
+  | 'taskResize:cancelled'
+  /** A `beforeProgressChange` handler refused the progress change. */
+  | 'progressChange:cancelled'
+  /** A `beforeMilestoneMove` handler refused the milestone move. */
+  | 'milestoneMove:cancelled'
+  /** A `beforeDependencyCreate` handler refused the links. */
+  | 'dependencyCreate:cancelled'
+  /** A `beforeTaskDelete` handler refused the delete. */
+  | 'taskDelete:cancelled';
+
+/** What a handler receives, per Gantt event. */
+interface GanttEventPayloads {
+  /** The recomputed schedule, exactly as `gantt.schedule` now reads. */
+  schedule: GanttSchedule;
+  /** Why the recompute failed. */
+  error: GanttScheduleError;
+  /** The edit about to be applied, with `preventDefault` to stop it. */
+  beforeTaskEdit: GanttTaskEditEvent;
+  /** The move about to be applied, with `preventDefault` to stop it. */
+  beforeTaskMove: GanttTaskEditEvent;
+  /** The resize about to be applied, with `preventDefault` to stop it. */
+  beforeTaskResize: GanttTaskEditEvent;
+  /** The progress about to be written, with `preventDefault` to stop it. */
+  beforeProgressChange: GanttTaskEditEvent;
+  /** The milestone move about to be applied, with `preventDefault` to stop it. */
+  beforeMilestoneMove: GanttTaskEditEvent;
+  /** The links about to be created, with `preventDefault` to stop them. */
+  beforeDependencyCreate: GanttDependencyCreateEvent;
+  /** The task about to be deleted, with `preventDefault` to stop it. */
+  beforeTaskDelete: GanttTaskDeleteEvent;
+  /** The edit that was not applied, and why. */
+  'taskEdit:cancelled': GanttTaskEditCancelledEvent;
+  /** The move that was not applied, and why. */
+  'taskMove:cancelled': GanttTaskEditCancelledEvent;
+  /** The resize that was not applied, and why. */
+  'taskResize:cancelled': GanttTaskEditCancelledEvent;
+  /** The progress change that was not written, and why. */
+  'progressChange:cancelled': GanttTaskEditCancelledEvent;
+  /** The milestone move that was not applied, and why. */
+  'milestoneMove:cancelled': GanttTaskEditCancelledEvent;
+  /** The links that were not created, and why. */
+  'dependencyCreate:cancelled': GanttDependencyCreateCancelledEvent;
+  /** The task that was not deleted, and why. */
+  'taskDelete:cancelled': GanttTaskDeleteCancelledEvent;
+}
+
 /** A headless Gantt controller: holds the model, recomputes on edits, emits changes. */
 interface Gantt {
+  /**
+   * The current tasks, as fresh shallow copies — mutating them changes nothing; call
+   * `applyEdit` or `setTasks`.
+   */
   readonly tasks: GanttTask[];
+  /**
+   * The current links, as fresh copies, always in the normalised `{ from, to, type, lag
+   * }` form.
+   */
   readonly dependencies: GanttDependency[];
+  /**
+   * The latest schedule result. It keeps the last successful one when a recompute fails,
+   * so a cycle does not blank the view.
+   */
   readonly schedule: GanttSchedule | null;
+  /** The critical task ids from the latest schedule; empty when the last compute failed. */
   readonly critical: string[];
   /** Constraints the latest schedule could not honour (empty when all are satisfied). */
   readonly conflicts: GanttConflict[];
+  /**
+   * Whether the controller was asked to cascade an edit down the dependency chain rather
+   * than only recomputing.
+   */
   readonly autoSchedule: boolean;
+  /** The grid this controller is bound to, or null for a standalone plan. */
   readonly grid: unknown;
   /** The over-allocations from the latest schedule. */
   readonly overAllocations: GanttOverAllocation[];
   /** The latest resource-load report, or null before a successful schedule. */
   readonly resourceLoad: GanttResourceLoad | null;
+  /**
+   * Replace the whole task list (copied in) and recompute, returning the new schedule.
+   * Ignored with a warning after `destroy()`.
+   */
   setTasks(tasks: GanttTask[]): GanttSchedule;
+  /**
+   * Replace the link list and recompute. Adding a link is gated on
+   * `beforeDependencyCreate`, so this returns undefined on a veto, or a promise when a
+   * handler defers; a pure removal or reorder applies straight away.
+   */
   setDependencies(deps: GanttDependency[]): GanttSchedule;
   /**
    * Apply one task edit and recompute — the single gated choke point every
@@ -311,7 +820,16 @@ interface Gantt {
    * resize stretches it across the new span at the same daily levels.
    */
   applyEdit(patch: { id: string | number; start?: number; end?: number; duration?: number; percentComplete?: number; work?: number | Array<{ date: number | string | Date; hours: number }> }, editOpts?: { writeBack?: boolean }): GanttSchedule;
+  /**
+   * Recompute the schedule now and return it. On success it emits `schedule` and
+   * refreshes the resource load; on a cycle or bad input it emits `error` and leaves the
+   * previous schedule in place.
+   */
   compute(): GanttSchedule;
+  /**
+   * The tasks placed earlier than CPM allows — the "manual with validation" flag. Empty
+   * when every placement is feasible, and when there is no successful schedule.
+   */
   findViolations(): GanttViolation[];
   /**
    * Compute the resource load and over-allocations on demand,
@@ -350,8 +868,14 @@ interface Gantt {
       added: GanttTask[]; updated: GanttTask[]; removed: string[];
     };
   };
-  on(event: 'schedule' | 'error', fn: (payload: unknown) => void): () => void;
-  off(event: 'schedule' | 'error', fn: (payload: unknown) => void): void;
+  /**
+   * Register an event listener; returns a function that unsubscribes. What each event
+   * carries is {@link GanttEventPayloads}; the listener is declared with the widest of
+   * them, so narrow on the name inside it.
+   */
+  on(event: GanttEventName, fn: (payload: GanttEventPayloads[GanttEventName]) => void): () => void;
+  /** Remove a listener registered with `on`. */
+  off(event: GanttEventName, fn: (payload: GanttEventPayloads[GanttEventName]) => void): void;
   /**
    * Render the plan into a container as an SVG timeline (bars, dependency
    * arrows, critical-path highlight, today line, non-working shading,
@@ -552,6 +1076,11 @@ interface Gantt {
   unmount(): void;
   /** The mounted view, or null. */
   readonly view: unknown;
+  /**
+   * Destroy the mounted view, drop the grid subscriptions and clear the listeners. The
+   * controller then refuses further edits with a warning; the host still owns the grid
+   * and the container.
+   */
   destroy(): void;
 }
 
@@ -615,11 +1144,33 @@ export default createGantt;
 
 /** The model {@link importMSPDI} returns and {@link exportMSPDI} takes. */
 interface GanttMSPDIModel {
+  /**
+   * The plan's tasks, written out with their outline level, summary and milestone flags,
+   * constraints, baseline and progress.
+   */
   tasks: GanttTask[];
+  /** The typed links, written as predecessor links with their lag on the successor task. */
   dependencies?: GanttDependency[];
+  /**
+   * The resource list, written with each resource's capacity as `MaxUnits`. Only the
+   * array form is read here: a name-to-capacity map is ignored, and its resources then
+   * appear only through the tasks' assignments, at capacity 1.
+   */
   resources?: GanttResourceSpec;
+  /**
+   * The project's start date. Defaults to the schedule's own start when a schedule is
+   * supplied.
+   */
   projectStart?: number | string | Date;
+  /**
+   * The working-time calendar written as the project's base calendar — a `weekends`
+   * preset or explicit workdays and holidays. Null writes no calendar.
+   */
   calendar?: GanttCalendar | null;
+  /**
+   * A computed schedule, so the written start and finish dates are the scheduled ones.
+   * Without it (or with a failed one) the tasks' own placements are used.
+   */
   schedule?: GanttSchedule;
 }