React Gantt Chart

@Grkmyldz148/react-gantt-chart is a flexible and customizable Gantt chart component built with React, TypeScript, and Tailwind CSS. It's designed to be easily integrated into modern web applications for visualizing project timelines, tasks, and epics.

Features

• Interactive Timeline: Drag and resize tasks and epics directly on the chart.
• Multiple View Modes: View the timeline in Quarters, Months, or Weeks.
• Zoom Functionality: Zoom in and out for different levels of detail.
• Customizable Date Range: Select start and end years for the timeline display.
• Epic and Task Management: Supports nested tasks within epics and standalone tasks.
• Expand/Collapse Epics: Easily manage visibility of tasks within epics.
• Drag & Drop Reordering: Reorder epics and tasks within the sidebar.
• Progress Tracking: Visualize task and epic progress with progress bars.
• Theming: Extensive customization options for light and dark modes using customColors (for non-border styles) and customBorders (for border styles) props.
• Internationalization (i18n): Support for multiple languages via the language and translations props.
• Customizable Controls: Show or hide specific timeline controls (zoom, year range, view mode selector, jump to start).
• Responsive Day Widths: Adjust the width of days in different views (weeks, months, quarters) using the dayWidths prop.
• Tooltip Control: Globally enable or disable tooltips for bars using showTooltips.
• Flexible Month Cell Formatting: Customize how months are displayed in the Quarter view (short, long, numeric).

Monorepo Structure

This project is a monorepo managed with npm/yarn workspaces (implicitly, as per package.json structure) and consists of:

• packages/react-gantt-chart: The source code for the Gantt chart library itself.
• examples/basic: A basic Vite + React application demonstrating the usage of the react-gantt-chart library.

Getting Started

Prerequisites

• Node.js (v18 or later recommended)
• yarn (or npm)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd react-gantt-chart-monorepo

2. Install dependencies from the root: This will install dependencies for both the library and the example application.

   yarn install
   # or
   # npm install

Development

Running the Library in Development Mode

To develop the react-gantt-chart library itself, you can run its Vite dev server. This is useful for isolated development and testing of library components.

cd packages/react-gantt-chart
yarn dev
# or
# npm run dev

This will typically start a dev server on http://localhost:5173 (or another port if configured).

Running the Example Application

The example application (examples/basic) consumes the local react-gantt-chart package. This is the recommended way to see the library in action and test its integration.

cd examples/basic
yarn dev
# or
# npm run dev

This will start the example app, usually on http://localhost:3001. Changes made in packages/react-gantt-chart/src will be hot-reloaded in the example app.

Linting and Typechecking

Run the following commands from the root of the monorepo:

• Lint:

  yarn lint
  # or
  # npm run lint

• Typecheck:

  yarn typecheck
  # or
  # npm run typecheck

Building for Production

Building the Library

To build the react-gantt-chart library for production:

cd packages/react-gantt-chart
yarn build
# or
# npm run build

This will generate the distributable files in packages/react-gantt-chart/dist.

Building the Example Application

To build the example application for production:

cd examples/basic
yarn build
# or
# npm run build

This will generate the production build in examples/basic/dist.

Using the Library in Your Project

Installation

Once the library is published (e.g., to npm), you can install it in your project:

npm install @Grkmyldz148/react-gantt-chart
# or
yarn add @Grkmyldz148/react-gantt-chart

Basic Usage

Import the Timeline component and its necessary CSS. You'll also need useTimelineData for managing the Gantt data.

import React, { useState } from 'react';
import {
  Timeline,
  useTimelineData,
  Epic,
  Task,
  // ... other types and props as needed
} from '@Grkmyldz148/react-gantt-chart';
import '@Grkmyldz148/react-gantt-chart'; // Imports the library's CSS

// Your application's main CSS (e.g., for Tailwind base styles)
import './index.css';

const initialEpicsData: Epic[] = [
  // ... your epic data
];
const initialStandaloneTasksData: Task[] = [
  // ... your standalone task data
];

function MyApp() {
  const [selectedStartYear, setSelectedStartYear] = useState(new Date().getFullYear());
  const [selectedEndYear, setSelectedEndYear] = useState(new Date().getFullYear() + 1);

  const { 
    epics,
    standaloneTasks,
    items,
    updateTask,
    updateEpic,
    moveTask,
    handleToggleExpand,
    handleReorderEpics 
  } = useTimelineData({
    initialEpics: initialEpicsData,
    initialStandaloneTasks: initialStandaloneTasksData,
    onEpicsChange: (updatedEpics) => console.log('Epics changed:', updatedEpics),
    onStandaloneTasksChange: (updatedTasks) => console.log('Tasks changed:', updatedTasks),
  });

  const handleYearRangeChange = (start: number, end: number) => {
    setSelectedStartYear(start);
    setSelectedEndYear(end);
  };

  return (
    <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
      {/* Add any controls for year range, dark mode, etc. here */}
      <div style={{ flexGrow: 1 }}>
        <Timeline
          epics={epics}
          standaloneTasks={standaloneTasks}
          items={items}
          selectedStartYear={selectedStartYear}
          selectedEndYear={selectedEndYear}
          onUpdateTask={updateTask}
          onUpdateEpic={updateEpic}
          onMoveTask={moveTask}
          onToggleExpand={handleToggleExpand}
          onReorderEpics={handleReorderEpics}
          onYearRangeChange={handleYearRangeChange}
          // Other props like customColors, customBorders, isDarkMode, language, etc.
        />
      </div>
    </div>
  );
}

export default MyApp;

Key Props and Customization

The Timeline component accepts various props to customize its behavior and appearance:

• Data Props:
  • epics: Epic[]: Array of epic objects.
  • standaloneTasks: Task[]: Array of task objects not belonging to any epic.
  • items: TimelineItem[]: A flattened list of all items (epics, tasks, section headers) to be rendered. Typically derived from epics and standaloneTasks via useTimelineData.
• Date Range:
  • selectedStartYear: number: The starting year for the timeline view.
  • selectedEndYear: number: The ending year for the timeline view.
• Event Handlers:
  • onUpdateTask: (taskId: string, updates: Partial<Task>) => void: Callback when a task is updated (e.g., dragged, resized).
  • onUpdateEpic: (epicId: string, updates: Partial<Epic>) => void: Callback when an epic is updated.
  • onMoveTask: (taskId: string, targetEpicId: string | null, targetIndex?: number) => void: Callback when a task is moved (e.g., to another epic or reordered).
  • onToggleExpand: (epicId: string) => void: Callback when an epic's expansion state is toggled.
  • onReorderEpics: (sourceIndex: number, targetIndex: number) => void: Callback when epics are reordered in the sidebar.
  • onYearRangeChange: (start: number, end: number) => void: Callback when the year range is changed via controls.
• Appearance & Theming:
  • customColors?: CustomColors: An object to define custom non-border color themes for light and dark modes. See src/types/timeline.ts for the structure (ComponentThemes, ElementThemeColors).
  • customBorders?: CustomBorders: An object to define custom border color themes for light and dark modes. See src/types/timeline.ts for the structure (ComponentBorderThemes, ElementBorderColors).
  • isDarkMode?: boolean: Toggles dark mode. Defaults to false.
  • showProgressBars?: boolean: Whether to show progress bars on tasks and epics. Defaults to true.
• Internationalization (i18n):
  • language?: string: The current language code (e.g., 'en', 'tr', 'fr'). Defaults to 'en'.
  • translations?: Translations: An object containing translation strings for different languages. See src/types/timeline.ts for TranslationKey and structure.
• View & Controls Configuration:
  • defaultViewMode?: ViewMode: Initial view mode ('quarters', 'months', 'weeks'). Defaults to 'quarters'.
  • timelineControlsConfig?: TimelineControlsConfig: Object to configure visibility of individual controls (e.g., { showZoomControls: false }).
    • showJumpToStartButton?: boolean
    • showZoomControls?: boolean
    • showYearRangeControls?: boolean
    • showViewModeSelector?: boolean
  • monthCellFormatInQuarterView?: MonthCellFormat: How months are displayed in the Quarter view's sub-header ('short', 'long', 'numeric'). Defaults to 'short'.
  • showTooltips?: boolean: Globally enable/disable tooltips for task/epic bars. Defaults to true.
  • dayWidths?: DayWidths: Object to specify custom widths for days in different views (e.g., { weeks: 70, months: 35, quarters: 20 }).

useTimelineData Hook

This hook is essential for managing the state of your Gantt chart data.

const {
  epics,              // Current state of epics
  standaloneTasks,    // Current state of standalone tasks
  items,              // Derived, flattened list for rendering
  updateTask,         // Function to update a task
  updateEpic,         // Function to update an epic
  moveTask,           // Function to move a task between/within epics or to standalone
  handleToggleExpand, // Function to toggle epic expansion
  handleReorderEpics, // Function to reorder epics
} = useTimelineData({
  initialEpics: yourInitialEpics,             // Optional: Initial epics data
  initialStandaloneTasks: yourInitialTasks, // Optional: Initial standalone tasks data
  onEpicsChange: (updatedEpics) => { /* Handle epic changes, e.g., save to backend */ },
  onStandaloneTasksChange: (updatedTasks) => { /* Handle task changes */ },
});

Contributing

Contributions are welcome! Please follow the standard fork, branch, commit, and pull request workflow. Ensure that your code passes linting and typechecking before submitting a PR.

License

This project is licensed under the MIT License.