jordium-gantt-vue3/README.md

A modern, flexible, and feature-rich Gantt chart component library for Vue 3

# jordium-gantt-vue3

[![npm version](https://img.shields.io/npm/v/jordium-gantt-vue3.svg?cacheBust=1)](https://www.npmjs.com/package/jordium-gantt-vue3)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Vue 3](https://img.shields.io/badge/vue-3.x-green.svg)](https://vuejs.org/)
[![TypeScript](https://img.shields.io/badge/typescript-5.x-blue.svg)](https://www.typescriptlang.org/)

A modern, flexible, and feature-rich Gantt chart component library for Vue 3. Built with TypeScript, supporting drag-and-drop, milestone management, task relationships, theme switching, and internationalization.

## ✨ Features

- 🎯 **Task Management**: Create, edit, delete tasks with full CRUD support
- 📅 **Timeline View**: Interactive timeline with drag-and-drop functionality  
- 🎯 **Milestone Support**: Add and manage project milestones
- 🔗 **Task Dependencies**: Support for predecessor relationships
- 🎨 **Dual Themes**: Light and dark mode with smooth transitions
- 🌍 **Internationalization**: Built-in Chinese and English support
- 📱 **Responsive Design**: Works seamlessly on desktop and mobile
- 🔧 **Highly Customizable**: Rich API and event system
- 💎 **TypeScript Support**: Full type safety for better development experience

## 📦 Installation

```bash
npm install jordium-gantt-vue3
# or
yarn add jordium-gantt-vue3
# or  
pnpm add jordium-gantt-vue3
```

## 🚀 Quick Start

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { GanttChart } from 'jordium-gantt-vue3'
import 'jordium-gantt-vue3/dist/style.css'

const tasks = ref([
  {
    id: 1,
    name: 'Project Kickoff',
    startDate: '2025-01-01',
    endDate: '2025-01-15',
    progress: 80,
    assignee: 'John Doe'
  },
  {
    id: 2,
    name: 'Requirements Analysis', 
    startDate: '2025-01-16',
    endDate: '2025-01-30',
    progress: 60,
    assignee: 'Jane Smith',
    predecessor: '1'
  }
])

const milestones = ref([
  {
    id: 1,
    name: 'Project Milestone',
    startDate: '2025-01-31',
    type: 'milestone'
  }
])
</script>

<template>
  <div style="height: 600px;">
    <GanttChart 
      :tasks="tasks" 
      :milestones="milestones"
    />
  </div>
</template>
```

## 🔧 API Reference

### Core Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `tasks` | `Task[]` | `[]` | Task data array |
| `milestones` | `Task[]` | `[]` | Milestone data array |
| `useDefaultDrawer` | `boolean` | `true` | Use default edit drawer |
| `showToolbar` | `boolean` | `true` | Show toolbar |
| `toolbarConfig` | `ToolbarConfig` | `{}` | Toolbar configuration |
| `localeMessages` | `object` | - | Custom locale messages |

### Event Callbacks

| Property | Type | Description |
|----------|------|-------------|
| `onTaskDoubleClick` | `(task: Task) => void` | Task double-click callback |
| `onTaskDelete` | `(task: Task) => void` | Task delete callback |
| `onTaskUpdate` | `(task: Task) => void` | Task update callback |
| `onTaskAdd` | `(task: Task) => void` | Task add callback |
| `onMilestoneSave` | `(milestone: Task) => void` | Milestone save callback |
| `onMilestoneDelete` | `(id: number) => void` | Milestone delete callback |
| `onLanguageChange` | `(lang: string) => void` | Language change callback |
| `onThemeChange` | `(isDark: boolean) => void` | Theme change callback |

### Events

| Event | Parameters | Description |
|-------|------------|-------------|
| `@taskbar-drag-end` | `task: Task` | Task drag ended |
| `@taskbar-resize-end` | `task: Task` | Task resize ended |
| `@milestone-drag-end` | `milestone: Task` | Milestone drag ended |

### Task Data Structure

```typescript
interface Task {
  id: number                    // Unique task identifier
  name: string                  // Task name
  predecessor?: string          // Predecessor task ID
  assignee?: string            // Assignee
  startDate?: string           // Start date (YYYY-MM-DD format)
  endDate?: string             // End date (YYYY-MM-DD format)
  progress?: number            // Completion progress (0-100)
  estimatedHours?: number      // Estimated hours
  actualHours?: number         // Actual hours
  parentId?: number            // Parent task ID
  children?: Task[]            // Child tasks array (supports nested structure)
  collapsed?: boolean          // Whether child tasks are collapsed
  isParent?: boolean           // Whether it's a parent task
  type?: string               // Task type (task/story/bug/milestone)
  description?: string         // Task description
  icon?: string               // Task icon
  level?: number              // Task level
}
```
### TimelineConfig Data Structure

```typescript
interface TimelineConfig {
  startDate: Date              // Timeline start date
  endDate: Date                // Timeline end date
  zoomLevel: number            // Zoom level
}
```

### ToolbarConfig Data Structure

```typescript
interface ToolbarConfig {
  showAddTask?: boolean        // Show add task button
  showAddMilestone?: boolean   // Show add milestone button
  showTodayLocate?: boolean    // Show locate today button
  showExportCsv?: boolean      // Show export CSV button
  showExportPdf?: boolean      // Show export PDF button
  showLanguage?: boolean       // Show language switch button
  showTheme?: boolean          // Show theme switch button
  showFullscreen?: boolean     // Show fullscreen toggle button
}
```

## 🎨 Advanced Usage

### Custom Event Handling

```vue
<script setup lang="ts">
import { GanttChart } from 'jordium-gantt-vue3'

const handleTaskDoubleClick = (task) => {
  console.log('Task clicked:', task)
  // Open custom edit dialog
}

const handleTaskDragEnd = (task) => {
  console.log('Task moved:', task)
  // Save changes to backend
}

const toolbarConfig = {
  showAddTask: true,
  showTheme: true,
  showLanguage: true,
  showExportCsv: true
}
</script>

<template>
  <GanttChart
    :tasks="tasks"
    :milestones="milestones"
    :toolbar-config="toolbarConfig"
    :on-task-double-click="handleTaskDoubleClick"
    @taskbar-drag-end="handleTaskDragEnd"
  />
</template>
```

### Internationalization

```vue
<script setup>
const customLocaleMessages = {
  taskName: 'Custom Task Name',
  addTask: 'Custom Add Task'
}
</script>

<template>
  <GanttChart
    :locale-messages="customLocaleMessages"
    :on-language-change="(lang) => console.log('Language:', lang)"
  />
</template>
```

## 📚 Documentation & Resources

- 📖 **Full Documentation**: [GitHub Repository](https://github.com/nelson820125/jordium-gantt-vue3)
- 📋 **Changelog**: [CHANGELOG.md](https://github.com/nelson820125/jordium-gantt-vue3/blob/main/CHANGELOG.md)
- 🐛 **Issues**: [GitHub Issues](https://github.com/nelson820125/jordium-gantt-vue3/issues)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/nelson820125/jordium-gantt-vue3/blob/main/CONTRIBUTING.md) for details.

## 📄 License

[MIT License](https://opensource.org/licenses/MIT) © 2025 Jordium.com

## 📧 Support

- 📬 **GitHub Issues**: [Report bugs or request features](https://github.com/nelson820125/jordium-gantt-vue3/issues)
- 📧 **Email**: ning.li@jordium.com / nelson820125@gmail.com
- 💼 **Business**: For enterprise support and custom development

---

> 💡 If this project helps you, please give it a ⭐ Star on GitHub!