API & types

The reference surface: what each package exports, the data-model interfaces, the scene shape, and the tables for events, services and commands. Types are shown in TypeScript; the packages ship .d.ts so your editor knows all of this.

Data model

type ViewMode = 'Day' | 'Week' | 'Month'

interface Task {
  id: string
  name: string
  start: string | Date
  end: string | Date
  kind?: 'task' | 'milestone'
  progress?: number            // 0–1
  dependencies?: string[]      // predecessor task ids
  className?: string
  draggable?: boolean
  tooltip?: string
  [key: string]: unknown       // extra fields for column formatters
}

interface Row {
  id: string
  name: string
  tasks: Task[]
  level?: number
  parentId?: string
  hasChildren?: boolean
  expanded?: boolean
  [key: string]: unknown
}

Engine options

interface GanttOptions {
  rows?: Row[]
  viewMode?: ViewMode          // 'Week'
  startDate?: string | Date | null
  endDate?: string | Date | null
  rowHeight?: number           // 50
  dayWidth?: number            // 60 (× 1.5 Day, × 1 Week, × 0.5 Month)
  barPadding?: number          // 6
  highlightToday?: boolean     // true
  draggable?: boolean          // true
  virtualize?: boolean         // true
  overscanRows?: number        // 4
  overscanCols?: number        // 6
  dateAdapter?: DateAdapter    // defaultDateAdapter
}

GanttEngine

Full method list see The core engine for descriptions.

class GanttEngine {
  // registries (public fields)
  events: EventBus
  commands: CommandRegistry
  services: ServiceRegistry
  ui: UiRegistry
  hooks: { rows: Hook; scene: Hook }
  store: Store

  constructor(options?: GanttOptions)

  // plugins
  use(plugin: Plugin): this
  hasPlugin(name: string): boolean
  removePlugin(name: string): void
  destroy(): void

  // read
  getState(): GanttState
  getOptions(): ResolvedOptions
  getRows(): Row[]
  getScene(): Scene
  getTimeScale(): TimeScale
  getWindow(): Window | null

  // mutate
  setRows(rows: Row[]): void
  updateTask(id: string, patch: Partial<Task>): boolean
  updateTaskDates(id: string, start: string | Date, end: string | Date): boolean
  setViewMode(mode: ViewMode): void
  selectTask(id: string | null): void
  setLoading(loading: boolean): void
  setDateAdapter(adapter: DateAdapter): void
  setViewport(vp: Viewport): void
  setDragPreview(id: string, start: string | Date, end: string | Date): void
  clearDragPreview(): void
  refresh(): void

  // geometry
  hitTest(x: number, y: number): { taskId: string; handle: 'left' | 'right' | null } | null
  hitTestRegion(x1: number, y1: number, x2: number, y2: number): string[]

  // services (sugar over this.services)
  provide(key: string, service: unknown): () => void
  consume<T>(key: string): T | undefined
  onSceneChange(listener: (scene: Scene) => void): () => void
}

Scene

interface Scene {
  width: number
  height: number
  layers: SceneLayer[]
}
interface SceneLayer { name: string; primitives: ScenePrimitive[] }

type ScenePrimitive = RectPrim | LinePrim | PathPrim | PolygonPrim | TextPrim

interface BasePrim {
  key: string
  className?: string
  taskId?: string
  title?: string
  data?: Record<string, string | number>   // → data-* attributes
}
interface RectPrim    extends BasePrim { type: 'rect';    x; y; width; height; rx? }
interface LinePrim    extends BasePrim { type: 'line';    x1; y1; x2; y2 }
interface PathPrim    extends BasePrim { type: 'path';    d: string; markerEnd? }
interface PolygonPrim extends BasePrim { type: 'polygon'; points: string; transform? }
interface TextPrim    extends BasePrim { type: 'text';    x; y; text; anchor?; baseline? }

Base layer order (paint order): backgrounds → grid → dependencies → bars → handles → milestones → labels. Plugins splice their layers in relative to these.

Layout entry (passed to scene hooks)

interface TaskLayout {
  task: Task
  rowId: string
  rowIndex: number
  isMilestone: boolean
  x: number; y: number; width: number; height: number
  cy: number          // vertical centre  handy for milestones/connectors
}

TimeScale

class TimeScale {
  start: Date; end: Date; viewMode: ViewMode
  dayWidth: number
  totalDays: number
  width: number
  days: Day[]; weeks: Week[]; months: Month[]
  dateToX(date: Date): number
  xToDayIndex(x: number): number
}
interface Day {
  key: string; date: Date; dayOfMonth: number
  weekday: string; isWeekend: boolean; isToday: boolean; isoWeek: number
}

DateAdapter

Every date operation goes through this interface. Implement it (or spread defaultDateAdapter) for exotic calendars.

interface DateAdapter {
  parse(value: string | Date): Date
  startOfDay(d: Date): Date
  startOfMonth(d: Date): Date
  endOfMonth(d: Date): Date
  startOfWeek(d: Date): Date
  addDays(d: Date, n: number): Date
  diffDays(a: Date, b: Date): number
  isoWeek(d: Date): number
  isWeekend(d: Date): boolean
  isSameDay(a: Date, b: Date): boolean
  toKey(d: Date): string
  weekdayShort(d: Date): string
  monthLabel(d: Date): string
  monthShort(d: Date): string
}

createIntlAdapter(locale: string, options?: {
  weekStartsOn?: number   // 0=Sun … 6=Sat
  weekend?: number[]      // day indices
}): DateAdapter

Events

Service keys

Constants GANTT_VIEWPORT_SERVICE and UI_SLOTS are exported from core so you don't hardcode the strings.

Commands

Core exports

Everything @ganttkit/core exports. Most apps only touch the first row; the rest are the building blocks renderers and advanced plugins use.