gantt-renderer 0.1.2 → 0.3.0

package/dist/index.d.mts

@@ -1,13 +1,13 @@
 import { z } from "zod";
 
-//#region src/gantt-chart/validation/schemas.d.ts
+//#region src/lib/validation/schemas.d.ts
 declare const LinkTypeSchema: z.ZodEnum<{
   FS: "FS";
   SS: "SS";
   FF: "FF";
   SF: "SF";
 }>;
-declare const TaskTypeSchema: z.ZodEnum<{
+declare const TaskKindSchema: z.ZodEnum<{
   task: "task";
   project: "project";
   milestone: "milestone";
@@ -25,21 +25,36 @@ declare const SpecialDaySchema: z.ZodObject<{
   label: z.ZodOptional<z.ZodString>;
   className: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-declare const TaskSchema: z.ZodObject<{
+declare const TaskSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  kind: z.ZodLiteral<"task">;
+  durationHours: z.ZodNumber;
+  percentComplete: z.ZodDefault<z.ZodNumber>;
   id: z.ZodNumber;
   text: z.ZodString;
-  start_date: z.ZodString;
-  duration: z.ZodNumber;
+  startDate: z.ZodString;
   parent: z.ZodOptional<z.ZodNumber>;
-  progress: z.ZodDefault<z.ZodNumber>;
-  type: z.ZodDefault<z.ZodEnum<{
-    task: "task";
-    project: "project";
-    milestone: "milestone";
-  }>>;
+  color: z.ZodOptional<z.ZodString>;
+  data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"project">;
+  durationHours: z.ZodNumber;
+  percentComplete: z.ZodDefault<z.ZodNumber>;
   open: z.ZodDefault<z.ZodBoolean>;
+  id: z.ZodNumber;
+  text: z.ZodString;
+  startDate: z.ZodString;
+  parent: z.ZodOptional<z.ZodNumber>;
   color: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+  data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"milestone">;
+  id: z.ZodNumber;
+  text: z.ZodString;
+  startDate: z.ZodString;
+  parent: z.ZodOptional<z.ZodNumber>;
+  color: z.ZodOptional<z.ZodString>;
+  data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>], "kind">;
 declare const LinkSchema: z.ZodObject<{
   id: z.ZodNumber;
   source: z.ZodNumber;
@@ -50,23 +65,39 @@ declare const LinkSchema: z.ZodObject<{
     FF: "FF";
     SF: "SF";
   }>>;
+  data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 declare const GanttInputSchema: z.ZodObject<{
-  tasks: z.ZodArray<z.ZodObject<{
+  tasks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"task">;
+    durationHours: z.ZodNumber;
+    percentComplete: z.ZodDefault<z.ZodNumber>;
     id: z.ZodNumber;
     text: z.ZodString;
-    start_date: z.ZodString;
-    duration: z.ZodNumber;
+    startDate: z.ZodString;
     parent: z.ZodOptional<z.ZodNumber>;
-    progress: z.ZodDefault<z.ZodNumber>;
-    type: z.ZodDefault<z.ZodEnum<{
-      task: "task";
-      project: "project";
-      milestone: "milestone";
-    }>>;
+    color: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"project">;
+    durationHours: z.ZodNumber;
+    percentComplete: z.ZodDefault<z.ZodNumber>;
     open: z.ZodDefault<z.ZodBoolean>;
+    id: z.ZodNumber;
+    text: z.ZodString;
+    startDate: z.ZodString;
+    parent: z.ZodOptional<z.ZodNumber>;
     color: z.ZodOptional<z.ZodString>;
-  }, z.core.$strip>>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"milestone">;
+    id: z.ZodNumber;
+    text: z.ZodString;
+    startDate: z.ZodString;
+    parent: z.ZodOptional<z.ZodNumber>;
+    color: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>], "kind">>;
   links: z.ZodDefault<z.ZodArray<z.ZodObject<{
     id: z.ZodNumber;
     source: z.ZodNumber;
@@ -77,21 +108,48 @@ declare const GanttInputSchema: z.ZodObject<{
       FF: "FF";
       SF: "SF";
     }>>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   }, z.core.$strip>>>;
 }, z.core.$strip>;
+/** The raw, unvalidated input shape that consumers pass to {@link parseGanttInput}. */
+type GanttInputRaw = z.input<typeof GanttInputSchema>;
+/** Allowed dependency link type values: `'FS'`, `'SS'`, `'FF'`, or `'SF'`. */
 type LinkType = z.infer<typeof LinkTypeSchema>;
-type TaskType = z.infer<typeof TaskTypeSchema>;
+/** Allowed task kind values: `'task'`, `'project'`, or `'milestone'`. */
+type TaskKind = z.infer<typeof TaskKindSchema>;
 type SpecialDayKind = z.infer<typeof SpecialDayKindSchema>;
 type SpecialDay = z.infer<typeof SpecialDaySchema>;
+/**
+ * A task in the Gantt chart — discriminated by `kind` into leaf tasks,
+ * summary projects, and milestones.
+ *
+ * - **`kind: 'task'`** — A regular task with a colored bar and duration.
+ * - **`kind: 'project'`** — A summary/group row with a colored bar and optional tree state.
+ * - **`kind: 'milestone'`** — A zero-duration marker rendered as a diamond.
+ */
 type Task = z.infer<typeof TaskSchema>;
+/**
+ * A dependency link between two tasks. The `type` determines the scheduling constraint
+ * (e.g., finish-to-start, start-to-start).
+ */
 type Link = z.infer<typeof LinkSchema>;
+/**
+ * The complete input data for the chart.
+ *
+ * Pass a raw plain object (typed as {@link GanttInputRaw}) to
+ * {@link parseGanttInput} to validate and get back a typed {@link GanttInput}.
+ */
 type GanttInput = z.infer<typeof GanttInputSchema>;
-/** Parses raw external data. Throws ZodError on failure. */
-declare function parseGanttInput(raw: unknown): GanttInput;
-/** Returns null instead of throwing. */
-declare function safeParseGanttInput(raw: unknown): GanttInput | null;
+/**
+ * Parses raw external data.
+ *
+ * @param raw - The unvalidated input from the consumer.
+ * @returns The parsed and validated {@link GanttInput}.
+ * @throws {import('zod').ZodError} On schema validation failure.
+ */
+declare function parseGanttInput(raw: GanttInputRaw): GanttInput;
 //#endregion
-//#region src/gantt-chart/timeline/scale.d.ts
+//#region src/lib/timeline/scale.d.ts
 type TimeScale = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
 type ScaleConfig = {
   /** Pixel width of one column unit */columnWidth: number; /** Milliseconds per column unit */
@@ -100,30 +158,51 @@ type ScaleConfig = {
 };
 declare const SCALE_CONFIGS: Record<TimeScale, ScaleConfig>;
 //#endregion
-//#region src/gantt-chart/domain/tree.d.ts
+//#region src/lib/domain/tree.d.ts
+/**
+ * A task node in the render tree, combining the flat {@link Task} input data
+ * with computed hierarchy structure.
+ *
+ * Produced by {@link buildTaskTree}; consumed by virtualized row rendering
+ * and the timeline layout engine.
+ */
 type TaskNode = Task & {
-  children: TaskNode[]; /** 0 = root */
+  /** Array of child task nodes in the tree hierarchy. */children: TaskNode[]; /** 0 = root */
   depth: number;
 };
 /**
  * Builds a typed tree from a flat task array.
  * Order of tasks[] is irrelevant — parents need not precede children.
- * Throws if any parent reference is unresolvable.
+ *
+ * @param tasks - The flat array of tasks to convert into a tree.
+ * @returns Root-level {@link TaskNode} instances with populated `children`.
+ * @throws {GanttError} When a task references a `parent` id that does not exist,
+ *         when a parent cycle is detected, or when a `parent` points to a
+ *         milestone or leaf task.
  */
 declare function buildTaskTree(tasks: Task[]): TaskNode[];
 /**
  * Flattens a tree into a visible row list.
- * A node's children are included only when its id is in expandedIds.
+ * A node's children are included only when its id is in `expandedIds`.
+ *
+ * @param roots - The root-level {@link TaskNode} instances of the tree.
+ * @param expandedIds - Set of task IDs whose children should be rendered.
+ * @returns A depth-first flattened array of visible {@link TaskNode} items.
  */
 declare function flattenTree(roots: TaskNode[], expandedIds: ReadonlySet<number>): TaskNode[];
-/** Returns true when a node has children in the tree. */
+/**
+ * Returns `true` when a node has children in the tree.
+ *
+ * @param node - The {@link TaskNode} to inspect.
+ * @returns `true` if `node.children.length > 0`.
+ */
 declare function isParent(node: TaskNode): boolean;
 //#endregion
-//#region src/gantt-chart/timeline/pixelMapper.d.ts
+//#region src/lib/timeline/pixelMapper.d.ts
 type PixelMapper = {
   /** Date → x pixel offset from viewport start */toX: (date: Date) => number; /** x pixel offset → Date */
-  toDate: (x: number) => Date; /** Days → pixel width */
-  durationToWidth: (days: number) => number; /** Pixel width → days (float) */
+  toDate: (x: number) => Date; /** Hours → pixel width */
+  durationToWidth: (hours: number) => number; /** Pixel width → hours (float) */
   widthToDuration: (px: number) => number; /** The origin timestamp used for this mapper */
   originMs: number; /** Pixel width of one column unit */
   columnWidth: number;
@@ -131,10 +210,14 @@ type PixelMapper = {
 /**
  * Creates a stateless pixel mapper for the given scale and viewport start.
  * All conversions are O(1) arithmetic — safe to call in tight loops.
+ *
+ * @param scale - The active {@link TimeScale}.
+ * @param viewportStart - The leftmost date visible in the viewport.
+ * @returns A {@link PixelMapper} configured for the given viewport.
  */
 declare function createPixelMapper(scale: TimeScale, viewportStart: Date): PixelMapper;
 //#endregion
-//#region src/gantt-chart/timeline/layoutEngine.d.ts
+//#region src/lib/timeline/layoutEngine.d.ts
 declare const DENSITY: {
   readonly rowHeight: 44;
   readonly barHeight: 28;
@@ -153,7 +236,7 @@ type BarLayout = {
   width: number;
   height: number;
   progressWidth: number;
-  type: 'task' | 'project' | 'milestone';
+  kind: 'task' | 'project' | 'milestone';
   rowIndex: number; /** Center x; identical to x + width/2 or x for milestones */
   centerX: number;
   centerY: number;
@@ -161,16 +244,23 @@ type BarLayout = {
 /**
  * Computes pixel-space layout for all visible task rows.
  * Returns a map keyed by task id for O(1) lookup during link routing.
+ *
+ * @param rows - The flattened, visible {@link TaskNode} rows.
+ * @param mapper - The {@link PixelMapper} for coordinate conversion.
+ * @returns A `Map` from task ID to its computed {@link BarLayout}.
  */
 declare function computeLayout(rows: TaskNode[], mapper: PixelMapper): Map<number, BarLayout>;
 /**
  * Derives viewport bounds from task data with padding.
- * Returns [start, end] as UTC midnight dates.
+ *
+ * @param tasks - The task nodes to derive bounds from.
+ * @param paddingHours - Extra hours added before the earliest start and after the latest end. Defaults to `48`.
+ * @returns A tuple `[start, end]` of UTC midnight `Date` instances.
  */
-declare function deriveViewport(tasks: TaskNode[], paddingDays?: number): [Date, Date];
+declare function deriveViewport(tasks: TaskNode[], paddingHours?: number): [Date, Date];
 //#endregion
-//#region src/gantt-chart/locale.d.ts
-type LocaleLabelKey = 'aria_task' | 'aria_milestone' | 'add_subtask_title' | 'column_task_name' | 'column_start_time' | 'column_duration' | 'column_quarter';
+//#region src/lib/locale.d.ts
+type LocaleLabelKey = 'ariaTask' | 'ariaMilestone' | 'addSubtaskTitle' | 'columnTaskName' | 'columnStartDate' | 'columnDuration' | 'columnQuarter';
 type ChartLocale = {
   code: string;
   labels?: Partial<Record<LocaleLabelKey, string>>;
@@ -180,62 +270,124 @@ type ChartLocale = {
 };
 declare const EN_US_LABELS: Record<LocaleLabelKey, string>;
 declare const CHART_LOCALE_EN_US: ChartLocale;
-/**
- * Resolves a ChartLocale from either a full ChartLocale object or a BCP 47 string.
- * When given a string, derives weekStartsOn, weekNumbering, and weekendDays from CLDR conventions.
- */
-declare function resolveChartLocale(raw: ChartLocale | string | undefined): ChartLocale;
 /**
  * Derives the first day of week (0=Sun, 1=Mon, 6=Sat) from a BCP 47 code.
- * Uses Intl.Locale.getWeekInfo() where available (Chromium, Safari 15.4+),
+ * Uses `Intl.Locale.getWeekInfo()` where available (Chromium, Safari 15.4+),
  * with a CLDR-based fallback table for Firefox and older runtimes.
+ *
+ * @param code - A BCP 47 language tag (e.g. `'en-US'`, `'de-DE'`).
+ * @returns The first day of the week: `0` (Sunday), `1` (Monday), or `6` (Saturday).
  */
 declare function deriveWeekStartsOn(code: string): 0 | 1 | 6;
 /**
  * Derives the week numbering scheme from a BCP 47 code.
- * Europe and ISO-aligned regions default to 'iso'; Americas and others to 'us'.
+ * Europe and ISO-aligned regions default to `'iso'`; Americas and others to `'us'`.
+ *
+ * @param code - A BCP 47 language tag (e.g. `'en-US'`, `'de-DE'`).
+ * @returns The week numbering scheme: `'iso'`, `'us'`, or `'simple'`.
  */
 declare function deriveWeekNumbering(code: string): 'iso' | 'us' | 'simple';
 /**
  * Derives weekend days (0=Sun … 6=Sat) from a BCP 47 code.
- * Uses Intl.Locale.getWeekInfo() where available, with a CLDR-based fallback table.
+ * Uses `Intl.Locale.getWeekInfo()` where available, with a CLDR-based fallback table.
+ *
+ * @param code - A BCP 47 language tag (e.g. `'en-US'`, `'de-DE'`).
+ * @returns An array of weekend day indices (sorted ascending).
  */
 declare function deriveWeekendDays(code: string): number[];
+/**
+ * Resolves a {@link ChartLocale} from either a full `ChartLocale` object or a BCP 47 string.
+ * When given a string, derives `weekStartsOn`, `weekNumbering`, and `weekendDays` from CLDR conventions.
+ *
+ * @param raw - A {@link ChartLocale} object, a BCP 47 language tag string, or `undefined`.
+ * @returns A fully resolved {@link ChartLocale} with defaults applied.
+ */
+declare function resolveChartLocale(raw: ChartLocale | string | undefined): ChartLocale;
 /**
  * Formats a week number according to the specified scheme.
  *
  * - `'iso'`: ISO 8601 (week 1 contains the first Thursday; Monday start).
  * - `'us'`: Week 1 contains January 1; Sunday start.
  * - `'simple'`: `Math.ceil(dayOfYear / 7)`.
+ *
+ * @param date - The date to compute the week number for.
+ * @param scheme - The week numbering scheme: `'iso'`, `'us'`, or `'simple'`.
+ * @returns The week number as a positive integer.
  */
 declare function formatWeekNumber(date: Date, scheme: 'iso' | 'us' | 'simple'): number;
 /**
  * Formats a label template by replacing `{0}` with the given argument.
+ *
+ * @param template - The template string containing `{0}` as placeholder.
+ * @param arg - The value to substitute for `{0}`.
+ * @returns The formatted string with the placeholder replaced.
  */
 declare function formatLabel(template: string, arg: string): string;
 //#endregion
-//#region src/gantt-chart/domain/dependencies.d.ts
+//#region src/lib/domain/dependencies.d.ts
 /**
  * Detects circular dependencies in the link graph using DFS tri-colour marking.
- * Throws with a human-readable cycle path on detection.
- * Silent return = no cycles.
+ *
+ * @param tasks - The task list (used to build the vertex set).
+ * @param links - The dependency links defining the directed edges.
+ * @throws {GanttError} When a cycle is detected, with a human-readable cycle path.
  */
 declare function detectCycles(tasks: Task[], links: Link[]): void;
 /**
- * Returns true when all link source/target ids reference existing tasks.
- * Throws with details on failure.
+ * Validates that every link references existing task IDs and that no
+ * duplicate (source, target) pairs exist.
+ *
+ * @param tasks - The task list (used as the reference set of valid IDs).
+ * @param links - The dependency links to validate.
+ * @throws {GanttError} When any link references a non-existent source or target task,
+ *         when a non-FS link connects to/from a milestone, or when duplicate
+ *         (source, target) pairs exist.
  */
 declare function validateLinkRefs(tasks: Task[], links: Link[]): void;
 //#endregion
-//#region src/gantt-chart/domain/dateMath.d.ts
-/** Parses YYYY-MM-DD → UTC midnight Date. Throws on invalid input. */
+//#region src/lib/domain/dateMath.d.ts
+/**
+ * Parses `YYYY-MM-DD` → UTC midnight `Date`.
+ *
+ * @param dateStr - An ISO-8601 date string in `YYYY-MM-DD` format.
+ * @returns A `Date` representing UTC midnight of the given date.
+ * @throws {Error} When `dateStr` does not represent a valid date.
+ */
 declare function parseDate(dateStr: string): Date;
-/** Returns date + n days (exact ms arithmetic). */
+/**
+ * Returns `date + n` days using exact millisecond arithmetic.
+ *
+ * @param date - The base date.
+ * @param days - Number of days to add (may be negative).
+ * @returns A new `Date` offset by the given number of days.
+ */
 declare function addDays(date: Date, days: number): Date;
-/** Difference in days (float). Positive when b > a. */
+/**
+ * Returns `date + n` hours using exact millisecond arithmetic.
+ *
+ * @param date - The base date.
+ * @param hours - Number of hours to add (may be negative).
+ * @returns A new `Date` offset by the given number of hours.
+ */
+declare function addHours(date: Date, hours: number): Date;
+/**
+ * Difference in days (float). Positive when `b > a`.
+ *
+ * @param a - The earlier date.
+ * @param b - The later date.
+ * @returns The fractional number of days between the two dates.
+ */
 declare function diffDays(a: Date, b: Date): number;
+/**
+ * Difference in hours (float). Positive when `b > a`.
+ *
+ * @param a - The earlier date.
+ * @param b - The later date.
+ * @returns The fractional number of hours between the two dates.
+ */
+declare function diffHours(a: Date, b: Date): number;
 //#endregion
-//#region src/gantt-chart/rendering/linkRouter.d.ts
+//#region src/lib/rendering/linkRouter.d.ts
 type Point = {
   x: number;
   y: number;
@@ -243,73 +395,113 @@ type Point = {
 type RoutedLink = {
   linkId: number;
   sourceTaskId: number;
-  targetTaskId: number; /** Ordered vertices of the orthogonal polyline (source → target). */
+  targetTaskId: number;
+  type: LinkType; /** Ordered vertices of the orthogonal polyline (source → target). */
   points: Point[];
 };
 /**
  * Computes orthogonal routing for all dependency links.
  * Links whose source or target is not in the layout map are skipped silently
  * (e.g. when the row is collapsed).
+ *
+ * @param links   - The dependency links to route.
+ * @param layouts - A map from task ID to its computed {@link BarLayout}.
+ * @returns An array of {@link RoutedLink} objects with computed vertex paths.
  */
 declare function routeLinks(links: Link[], layouts: Map<number, BarLayout>): RoutedLink[];
 //#endregion
-//#region src/gantt-chart/vanilla/dom/gridColumns.d.ts
+//#region src/lib/vanilla/dom/gridColumns.d.ts
+/**
+ * Union of all field names that can appear on any {@link Task} variant.
+ * Use when referencing task fields in grid column schemas that apply
+ * across a heterogeneous set of task kinds.
+ */
+type TaskDataField = keyof Task | 'durationHours' | 'percentComplete' | 'open';
 type GridColumn = {
   id: string;
   header: string;
   width: string;
   align?: 'left' | 'center' | 'right';
   visible?: boolean;
-  field?: keyof Task;
+  field?: TaskDataField;
   format?: (value: unknown, task: Task, row: TaskNode, locale: ChartLocale) => string;
 };
 declare const DEFAULT_GRID_COLUMNS: GridColumn[];
 /**
  * Returns a localized default grid column schema.
- * Column headers use locale label overrides with EN_US_LABELS fallback.
+ * Column headers use locale label overrides with `EN_US_LABELS` fallback.
+ *
+ * @param locale - The {@link ChartLocale} to derive column header labels from.
+ * @returns An array of {@link GridColumn} objects.
  */
 declare function gridColumnDefaults(locale: ChartLocale): GridColumn[];
+/**
+ * Builds a CSS `grid-template-columns` value from a column schema.
+ *
+ * @param columns - The full column schema array (only visible columns are included).
+ * @returns A space-separated CSS track list.
+ */
 declare function gridTemplateColumns(columns: GridColumn[]): string;
+/**
+ * Filters a column schema to only visible columns.
+ *
+ * @param columns - The full column schema array.
+ * @returns A new array containing only columns where `visible` is not `false`.
+ */
 declare function visibleColumns(columns: GridColumn[]): GridColumn[];
 declare const GRID_COLUMN_FR_MIN_WIDTH = 120;
+/**
+ * Computes the minimum natural pixel width of a grid column schema.
+ *
+ * @param columns - The full column schema array.
+ * @returns The sum of minimum widths: `px` columns sum directly, `fr` units contribute
+ *          `GRID_COLUMN_FR_MIN_WIDTH` px each.
+ */
 declare function gridNaturalWidth(columns: GridColumn[]): number;
 //#endregion
-//#region src/gantt-chart/vanilla/gantt-chart.d.ts
-type OnTaskSelect = (taskId: number | null) => void;
-type OnTaskMove = (payload: {
-  id: number;
-  startDate: Date;
+//#region src/lib/vanilla/gantt-chart.d.ts
+type OnTaskSelect = (payload: {
+  task: Task;
 }) => void;
+type OnTaskMove = (payload: {
+  task: Task;
+  newStartDate: Date;
+}) => boolean;
 type OnTaskResize = (payload: {
-  id: number;
-  duration: number;
-}) => void;
+  task: Task;
+  newDurationHours: number;
+}) => boolean;
 type OnTaskAdd = (payload: {
-  parentId: number;
-}) => void;
+  parentTask: Task;
+}) => boolean;
 type OnTaskDoubleClick = (payload: {
-  id: number;
-  source: 'grid' | 'bar' | 'milestone';
-}) => void;
-type OnTaskEditIntent = (payload: {
-  id: number;
-  source: 'grid' | 'bar' | 'milestone';
-  trigger: 'double_click';
   task: Task;
 }) => void;
 type OnLinkCreate = (payload: {
-  sourceTaskId: number;
-  targetTaskId: number;
   type: 'FS';
+  sourceTask: Task;
+  targetTask: Task;
+}) => boolean;
+type OnLinkClick = (payload: {
+  link: Link;
+}) => void;
+type OnLinkDblClick = (payload: {
+  link: Link;
 }) => void;
+type OnProgressChange = (payload: {
+  task: Task;
+  newPercentComplete: number;
+}) => boolean;
 type GanttCallbacks = {
-  onSelect?: OnTaskSelect;
-  onMove?: OnTaskMove;
-  onResize?: OnTaskResize;
-  onAdd?: OnTaskAdd;
+  onTaskSelect?: OnTaskSelect;
+  onTaskMove?: OnTaskMove;
+  onTaskResize?: OnTaskResize;
+  onTaskAdd?: OnTaskAdd;
   onTaskDoubleClick?: OnTaskDoubleClick;
-  onTaskEditIntent?: OnTaskEditIntent;
   onLinkCreate?: OnLinkCreate;
+  onLinkClick?: OnLinkClick;
+  onLinkDblClick?: OnLinkDblClick;
+  onProgressChange?: OnProgressChange;
   onLeftPaneWidthChange?: (width: number) => void;
   onGridColumnsChange?: (columns: GridColumn[]) => void;
 };
@@ -318,6 +510,7 @@ type GanttOptions = {
   scale?: TimeScale;
   highlightLinkedDependenciesOnSelect?: boolean;
   linkCreationEnabled?: boolean;
+  progressDragEnabled?: boolean;
   leftPaneWidth?: number;
   responsiveSplitPane?: boolean;
   mobileBreakpoint?: number;
@@ -333,32 +526,94 @@ type GanttOptions = {
   specialDays?: SpecialDay[];
   gridColumns?: GridColumn[];
   theme?: ThemeMode;
-} & GanttCallbacks;
+};
 type GanttInstance = {
   update: (input: GanttInput) => void;
-  setScale: (scale: TimeScale) => void;
+  setOptions: (opts: Partial<GanttOptions>) => void;
   select: (id: number | null) => void;
   collapseAll: () => void;
   expandAll: () => void;
   destroy: () => void;
 };
+/**
+ * Progressive-enhancement Gantt chart component.
+ * Validates input, builds a DOM tree, and renders a full interactive chart
+ * inside the given container element.
+ *
+ * @example
+ * ```ts
+ * const chart = new GanttChart(document.getElementById('chart')!, input, {
+ *   locale: 'de-DE',
+ *   theme: 'dark',
+ * });
+ * ```
+ */
 declare class GanttChart implements GanttInstance {
   #private;
-  constructor(container: HTMLElement, input: GanttInput, opts?: GanttOptions);
+  /**
+   * Constructs a new chart, builds the DOM, and wires internal event handling.
+   * Data must be loaded via {@link update} before the chart renders.
+   *
+   * @param container - The host `HTMLElement` the chart will be appended to.
+   * @param opts - Configuration and callback options.
+   */
+  constructor(container: HTMLElement, opts?: GanttOptions, cbs?: GanttCallbacks);
+  /**
+   * Replaces the full dataset and re-renders.
+   *
+   * @param newInput - The new {@link GanttInput} to apply.
+   * @throws {GanttError} When the instance has been destroyed.
+   */
   update(newInput: GanttInput): void;
-  setScale(scale: TimeScale): void;
+  /**
+   * Merges the supplied options into the current configuration and re-renders
+   * only the panes affected by the changed options.
+   *
+   * @param opts - A partial {@link GanttOptions} object. Only the keys present
+   *               in this parameter are updated; missing keys keep their
+   *               previous values.
+   * @throws {GanttError} When the instance has been destroyed.
+   */
+  setOptions(opts: Partial<GanttOptions>): void;
+  /**
+   * Programmatically selects or deselects a task.
+   *
+   * @param id - The task ID to select, or `null` to clear the selection.
+   * @throws {GanttError} When the instance has been destroyed.
+   */
   select(id: number | null): void;
+  /**
+   * Collapses all expandable groups in the task tree.
+   *
+   * @throws {GanttError} When the instance has been destroyed.
+   */
   collapseAll(): void;
+  /**
+   * Expands all expandable groups in the task tree.
+   *
+   * @throws {GanttError} When the instance has been destroyed.
+   */
   expandAll(): void;
+  /**
+   * Removes the chart DOM and internal listeners, rendering the instance
+   * unusable. Subsequent calls to any public method will throw.
+   */
   destroy(): void;
 }
 //#endregion
-//#region src/gantt-chart/errors.d.ts
-type GanttErrorCode = 'PARENT_REFERENCE' | 'LINK_REFERENCE' | 'DEPENDENCY_CYCLE' | 'INSTANCE_DESTROYED';
+//#region src/lib/errors.d.ts
+type GanttErrorCode = 'PARENT_REFERENCE' | 'PARENT_CYCLE' | 'LINK_REFERENCE' | 'DEPENDENCY_CYCLE' | 'MILESTONE_LINK_TYPE' | 'DUPLICATE_LINK_PAIR' | 'INSTANCE_DESTROYED';
+/**
+ * Domain-specific error with a machine-readable {@link GanttErrorCode}.
+ */
 declare class GanttError extends Error {
   readonly code: GanttErrorCode;
+  /**
+   * @param code - A machine-readable {@link GanttErrorCode} categorising the error.
+   * @param message - A human-readable description.
+   */
   constructor(code: GanttErrorCode, message: string);
 }
 //#endregion
-export { BAR_HEIGHT, BAR_Y_OFFSET, type BarLayout, CHART_LOCALE_EN_US, type ChartLocale, DEFAULT_GRID_COLUMNS, DENSITY, EN_US_LABELS, GRID_COLUMN_FR_MIN_WIDTH, type GanttCallbacks, GanttChart, GanttError, type GanttErrorCode, type GanttInput, GanttInputSchema, type GanttInstance, type GanttOptions, type GridColumn, type Link, LinkSchema, type LinkType, LinkTypeSchema, type LocaleLabelKey, MILESTONE_HALF, MILESTONE_SIZE, type OnLinkCreate, type OnTaskAdd, type OnTaskDoubleClick, type OnTaskEditIntent, type OnTaskMove, type OnTaskResize, type OnTaskSelect, type PixelMapper, type Point, ROW_HEIGHT, type RoutedLink, SCALE_CONFIGS, type ScaleConfig, type SpecialDay, type SpecialDayKind, SpecialDayKindSchema, SpecialDaySchema, type Task, type TaskNode, TaskSchema, type TaskType, TaskTypeSchema, type ThemeMode, type TimeScale, addDays, buildTaskTree, computeLayout, createPixelMapper, deriveViewport, deriveWeekNumbering, deriveWeekStartsOn, deriveWeekendDays, detectCycles, diffDays, flattenTree, formatLabel, formatWeekNumber, gridColumnDefaults, gridNaturalWidth, gridTemplateColumns, isParent, parseDate, parseGanttInput, resolveChartLocale, routeLinks, safeParseGanttInput, validateLinkRefs, visibleColumns };
+export { BAR_HEIGHT, BAR_Y_OFFSET, type BarLayout, CHART_LOCALE_EN_US, type ChartLocale, DEFAULT_GRID_COLUMNS, DENSITY, EN_US_LABELS, GRID_COLUMN_FR_MIN_WIDTH, type GanttCallbacks, GanttChart, GanttError, type GanttErrorCode, type GanttInput, type GanttInputRaw, GanttInputSchema, type GanttInstance, type GanttOptions, type GridColumn, type Link, LinkSchema, type LinkType, LinkTypeSchema, type LocaleLabelKey, MILESTONE_HALF, MILESTONE_SIZE, type OnLinkClick, type OnLinkCreate, type OnLinkDblClick, type OnProgressChange, type OnTaskAdd, type OnTaskDoubleClick, type OnTaskMove, type OnTaskResize, type OnTaskSelect, type PixelMapper, type Point, ROW_HEIGHT, type RoutedLink, SCALE_CONFIGS, type ScaleConfig, type SpecialDay, type SpecialDayKind, SpecialDayKindSchema, SpecialDaySchema, type Task, type TaskDataField, type TaskKind, TaskKindSchema, type TaskNode, TaskSchema, type ThemeMode, type TimeScale, addDays, addHours, buildTaskTree, computeLayout, createPixelMapper, deriveViewport, deriveWeekNumbering, deriveWeekStartsOn, deriveWeekendDays, detectCycles, diffDays, diffHours, flattenTree, formatLabel, formatWeekNumber, gridColumnDefaults, gridNaturalWidth, gridTemplateColumns, isParent, parseDate, parseGanttInput, resolveChartLocale, routeLinks, validateLinkRefs, visibleColumns };
 //# sourceMappingURL=index.d.mts.map