The core engine

GanttEngine is the whole system minus the pixels. It owns the reactive state, the time-scale, the layout, the plugin host and the compute pipeline that turns rows into a scene. This page is the map of its public surface.

Constructing the engine

Every option has a default, so new GanttEngine() is valid (it renders an empty three-month window). Construction runs one full compute pass immediately.

import { GanttEngine } from '@ganttkit/core'

const engine = new GanttEngine({
  rows,
  viewMode: 'Month',
  rowHeight: 44,
  highlightToday: true,
})

Options

Plugin lifecycle

Installing or removing a plugin triggers a full recompute, so the chart is always consistent.

Reading state

These accessors are read-only snapshots cheap to call in an event handler or render loop.

The store

State lives in a tiny observable store. Subscribers fire only when a shallow patch actually changes a reference, and re-entrant set() from a listener throws so update loops surface loudly instead of silently recursing.

const off = engine.store.subscribe((state, prev) => {
  if (state.viewMode !== prev.viewMode) console.log('view mode →', state.viewMode)
})
// …
off() // unsubscribe

Mutations

Mutations update state and run the appropriate compute pass. The heavy ones also emit a domain event.

Events

engine.events is an event bus with on, once, off and emit. Every on/once returns an unsubscribe function.

const off = engine.events.on('task:dragend', ({ task, start, end, changed }) => {
  if (changed) save(task.id, start, end)
})

The two-pass compute pipeline

Performance comes from splitting compute into a heavy pass and a cheap pass. The renderer picks which to run from the scene:change reason.

Concretely: setRows, setViewMode, use and refresh take the heavy path; setViewport (scroll) and setDragPreview take the cheap path. A 20 000-task chart rebuilds on scroll in under a millisecond because only the visible slice is ever laid out.

Virtualization & the viewport

The renderer measures its scroll container and calls setViewport, coalescing bursts to one call per animation frame. The engine resolves that into a window a row and day range plus overscan and emits only the primitives inside it.

engine.setViewport({
  scrollTop: body.scrollTop,
  scrollLeft: body.scrollLeft,
  width: body.clientWidth,
  height: body.clientHeight,
})

engine.getWindow() // { rowStart, rowEnd, dayStart, dayEnd } | null

If you build a custom renderer, wiring setViewport to your scroll/resize handlers is the one thing you must do to get virtualization.

The time-scale

getTimeScale() returns the object that maps between dates and pixels. It's the single source of truth for horizontal geometry, so plugins and renderers never re-derive it.

// Scroll so "today" sits ~30% from the left edge
const x = engine.getTimeScale().dateToX(new Date())
body.scrollLeft = Math.max(0, x - body.clientWidth * 0.3)

Hit-testing

"What's under the pointer" lives in the engine so no renderer or plugin re-implements geometry. Coordinates are in scene space (use the gantt:viewport service's clientToScene to convert).

Services

The core stays feature-agnostic through a service registry. A plugin publishes a capability under a string key; renderers and other plugins consume it. Keys are unique providing a taken key throws.

const off = engine.provide('gantt:sidebar', sidebarModel) // returns a disposer
const sidebar = engine.consume('gantt:sidebar')           // model | undefined

Built-in keys: gantt:sidebar (columns), gantt:i18n (i18n) and gantt:viewport (published by the renderer for client→scene coordinate mapping). See Writing a plugin for how to define your own.

Date adapters

All date logic goes through a DateAdapter. The default is Gregorian with a Monday week start. createIntlAdapter(locale, options?) builds a locale-aware one on top of Intl, and plugin-i18n swaps it in when the locale changes.

import { createIntlAdapter } from '@ganttkit/core'

engine.setDateAdapter(createIntlAdapter('fr-FR', {
  weekStartsOn: 1,   // 0=Sun … 6=Sat; inferred from the locale if omitted
  weekend: [0, 6],   // day indices treated as weekend
}))