GanttChart API Reference

Props

Prop	Type	Default	Description
viewMode	String	'daily'	Timeline view granularity: 'daily', 'weekly', 'monthly'

Events

Event	Payload	Description
update:viewMode	mode: String	Emitted when the view mode is changed (v-model compatible)

Pinia Store (ganttChart.store)

The GanttChart component relies on a Pinia store for state management.

State

Property	Type	Description
items	Array	Array of task/item objects to display in the Gantt chart
loadingItems	Array	Array of loading item states for async operations
ganttBoundaryStartDate	String | null	Start boundary for lazy-load observer (YYYY-MM-DD format)
ganttBoundaryEndDate	String | null	End boundary for lazy-load observer (YYYY-MM-DD format)
dependencies	Array	Legacy dependencies array
phasesList	Array	Array of project phase objects for task categorization

Item Object Structure

Each item in the items array should have the following structure:

interface GanttItem {
  _id: string;                    // Unique identifier
  title: string;                  // Task title/name
  startDate: string;              // ISO date string
  dueDate: string;                // ISO date string
  phase: {
    _id: string;
    name: string;
    colour: string;               // Hex color code
    textColor: string;            // Hex color code
  };
  ganttSeq: number;               // Sequence order in the chart
  predecessor: {                  // Predecessor task relationship
    taskId: string;               // ID of predecessor task
    title: string;                // Title of predecessor task
    lag: number;                  // Lag time (can be negative)
    type: string;                 // Dependency type: 'FF', 'FS', 'SF', 'SS'
  } | null;
  subItems: Array<GanttItem>;     // Nested sub-items
  statusName: string;             // Status: 'Not Started', 'In Progress', 'Pending', 'Completed'
}

Phase Object Structure

interface Phase {
  _id: string;
  name: string;
  colour: string;      // Background color (hex)
  textColor: string;   // Text color (hex)
}

Store Actions

Action	Parameters	Description
updateItemPosition	(item: Object, newPhaseObject: Object, newGanttSeq: number)	Update an item's position and phase with local resequencing
addLoadingItem	(itemId: string, itemData: Object, promise: Promise)	Add a loading state for an item during async operations
removeLoadingItem	(requestId: string)	Remove a loading state by request ID
isItemLoading	(itemId: string)	Check if an item is currently in loading state
getLoadingItemByRequestId	(requestId: string)	Get loading item data by request ID
updateLoadingItemPromise	(requestId: string, promise: Promise)	Update the promise for a loading item
updateItemTime	(id: string, newStart?: string, newEnd?: string)	Update a task's start and/or end date (YYYY-MM-DD format)
setPredecessor	(itemId: string, predecessor: Object)	Set a predecessor for a task
updatePredecessorLag	(item: Object, lag: number)	Update the lag time for a predecessor relationship
removePredecessor	(item: Object)	Remove the predecessor from a task

Store Usage Example

<script setup>
import { useGanttChart } from "@/stores/ganttChart.store";

const ganttStore = useGanttChart();

// Add a new task
ganttStore.items.push({
  _id: "task-123",
  title: "New Task",
  startDate: new Date().toISOString(),
  dueDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
  phase: {
    _id: "phase-1",
    name: "Development",
    colour: "#10b981",
    textColor: "#ffffff",
  },
  ganttSeq: 0,
  predecessor: null,
  subItems: [],
  statusName: "Not Started",
});

// Update task dates
ganttStore.updateItemTime("task-123", "2024-02-01", "2024-02-15");

// Access phases list
console.log(ganttStore.phasesList);

// Set boundary dates for lazy loading
ganttStore.ganttBoundaryStartDate = "2024-01-01";
ganttStore.ganttBoundaryEndDate = "2024-12-31";
</script>

Composables

useGanttZoomPan

Handles zoom and pan functionality.

Parameters

interface ZoomPanOptions {
  containerRef: Ref<HTMLElement>;      // Container element ref
  onScroll?: (scrollLeft: number) => void;  // Scroll callback
  onZoomChange?: () => void;           // Zoom change callback
  shouldIgnoreKeyEvent?: (event: KeyboardEvent) => boolean;  // Key event filter
}

Returns

interface ZoomPanReturn {
  zoomFactor: Ref<number>;             // Current zoom level (0.5 - 2)
  isSpacePressed: Ref<boolean>;        // Space key state
  isPanModeActive: Ref<boolean>;       // Pan mode state
  isPanning: Ref<boolean>;             // Currently panning
  onClickZoomControl: (type: 'plus' | 'minus') => void;
  onClickPanViewButton: () => void;
  setupContainerInteractions: () => void;
  teardownContainerInteractions: (el: HTMLElement) => void;
  setupWindowListeners: () => void;
  cleanup: () => void;
}

useGanttDatePicker

Manages date picker interactions.

Returns

interface DatePickerReturn {
  datePickerMenu: Ref<any>;            // Menu component ref
  datePickerTrigger: Ref<HTMLElement>; // Trigger element ref
  datePickerValue: Ref<Date | null>;   // Selected date
  datePickerTriggerStyle: Ref<object>; // Positioning styles
  datePickerPlacement: Ref<string>;    // Popup placement
  currentEditingItem: Ref<GanttItem | null>;
  currentDateType: Ref<'start' | 'end' | null>;
  datePickerJustClosed: Ref<boolean>;
  datePickerModelValue: ComputedRef<Date | null>;
  openDatePicker: (item: GanttItem, dateType: 'start' | 'end', event: Event, itemBarElement?: Element, onBeforeOpen?: () => void) => void;
  closeDatePicker: () => void;
  handleDateChange: (newDate: Date) => void;
  findItemBar: (target: Element) => Element | null;
  cleanup: () => void;
}

useGanttContextMenu

Manages context menu operations.

Returns

interface ContextMenuReturn {
  contextMenuMenu: Ref<any>;
  contextMenuTrigger: Ref<HTMLElement>;
  contextMenuItem: Ref<GanttItem | null>;
  contextMenuTriggerStyle: Ref<object>;
  contextMenuPlacement: Ref<string>;
  contextMenuItems: Ref<Array<{ _id: number; name: string }>>;
  contextMenuJustClosed: Ref<boolean>;
  openContextMenu: (item: GanttItem, event: Event, itemBarElement?: Element) => void;
  closeContextMenu: () => void;
  onContextMenuSelect: (menuItem: { name: string }) => void;
}

useGanttLazyLoading

Manages lazy loading for large datasets.

Parameters

interface LazyLoadingOptions {
  containerRef: Ref<HTMLElement>;      // Scroll container
  fetchItemsAPI?: (dateRange: { start: Date; end: Date; startFormatted: string; endFormatted: string }) => Promise<GanttItem[]>;
}

Returns

interface LazyLoadingReturn {
  isLoading: Ref<boolean>;
  lastFetchedRange: Ref<{ start: Date | null; end: Date | null }>;
  setupHorizontalObserver: () => void;
  observeDateIntervals: () => void;
  cleanupHorizontalObserver: () => void;
  fetchedDateRanges: Ref<Set<string>>;
  setInitialFetchedRange: (startDate: string, endDate: string) => void;
  cleanup: () => void;
}

Dependencies

The GanttChart component requires:

• Vue 3 with Composition API
• Pinia for state management
• D3.js for SVG rendering and interactions
• Moment.js for date manipulation
• OMenu component for dropdown menus
• Internal composables: useGanttZoomPan, useGanttDatePicker, useGanttContextMenu, useGanttLazyLoading

Browser Compatibility

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Accessibility

The GanttChart component includes:

• Keyboard navigation support (Space, Escape)
• ARIA labels for interactive elements
• Focus management for modals and menus
• Screen reader friendly date formats
• High contrast color support for phases

Performance Considerations

• Large Datasets: Enable lazy loading for 100+ items
• Zoom Operations: Debounced to prevent excessive re-renders
• DOM Updates: Uses D3.js data joins for efficient updates
• Event Listeners: Properly cleaned up on unmount
• Memory Management: Store only visible date ranges in memory