npm package: @rpui/vue-gantt-chart
Description: High-performance Vue 2.0 Gantt Chart Component with rich features
Author: Vue Gantt Team
Latest version: 1.0.0

# Vue Gantt Chart

High-performance Vue 2.0 Gantt Chart Component with rich features.

## 📦 Installation

```bash
# npm
npm install @your-org/vue-gantt-chart --save

# yarn
yarn add @your-org/vue-gantt-chart
```

## 🚀 Quick Start

### Global Registration

```javascript
import Vue from "vue";
import ElementUI from "element-ui";
import "element-ui/lib/theme-chalk/index.css";
import VueGanttChart from "@your-org/vue-gantt-chart";

// Use Element UI
Vue.use(ElementUI);

// Use Gantt Chart with options
Vue.use(VueGanttChart, {
  // Optional performance configuration
  performance: {
    RENDERING: {
      DRAG_THROTTLE: 16,
      SCROLL_THROTTLE: 16,
    },
  },
  // Optional feature configuration
  features: {
    experimental: {
      virtualScrolling: true,
      intelligentCaching: true,
    },
  },
});
```

### Local Registration

```javascript
import { GanttChart } from "@your-org/vue-gantt-chart";

export default {
  components: {
    GanttChart,
  },
};
```

### Basic Usage

```vue
<template>
  <div>
    <gantt-chart
      :data="ganttData"
      :tooltip-enabled="true"
      :show-progress="true"
      :show-connections="true"
      @task-updated="handleTaskUpdate"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      ganttData: [
        {
          id: 1,
          name: "Task 1",
          startDate: "2024-01-01",
          endDate: "2024-01-15",
          progress: 60,
        },
        {
          id: 2,
          name: "Task 2",
          startDate: "2024-01-10",
          endDate: "2024-01-25",
          progress: 30,
        },
      ],
    };
  },
  methods: {
    handleTaskUpdate(task) {
      console.log("Task updated:", task);
    },
  },
};
</script>
```

## 🚀 Features

### Core Functionality

- **Task Management**: Create, edit, and delete tasks
- **Progress Control**: Drag to adjust task progress percentage
- **Dependencies**: Visual task dependency connection lines
- **Milestones**: Support for milestone task types
- **Plan Comparison**: Display planned time vs actual time
- **Three-level Task Structure**: Support for parent->child->grandchild three-tier task nesting

### dhtmlx Style Interface

- **External Connection Points**: Professional connection points outside task bars
- **Smart Connection Lines**: Dependency lines with custom colors and labels
- **Progress Dragging**: dhtmlx-style progress adjustment handles
- **Connection Preview**: Real-time connection line preview during dragging
- **Professional Styling**: Shadows, rounded corners, animations and modern UI effects

### Interactive Features

- **Drag & Drop**: Task time adjustment and position movement
- **Resizing**: Drag task bar edges to adjust time range
- **Connection Line Editing**: Double-click connection lines to edit color and labels
- **Smart Tooltips**: Detailed task information tooltips
- **Keyboard Support**: Complete keyboard operation support

### Performance Optimization

- **Virtual Scrolling**: Optimized rendering for large datasets
- **RAF Optimization**: Smooth 60FPS animations
- **Caching Mechanism**: Dependency line calculation caching
- **Event Throttling**: Debounced user interactions
- **Auto Optimization**: Automatically enable performance optimization based on task count

### User Interface Optimization

- **Unified Settings Panel**: All control functions centralized in settings dialog
- **Streamlined Toolbar**: Only essential quick operations in toolbar
- **Smart Layout**: Adaptive interface layout to save space

## 🚀 Performance Optimization

### Drag Performance Optimization

To solve the stuttering issue when dragging nodes left and right, the project implements multi-layer performance optimization strategies:

#### Core Optimization Technologies

1. **RAF Throttling Mechanism**

   - Uses `requestAnimationFrame` to control drag update frequency
   - Limits update frequency to display refresh rate (usually 60fps)
   - Avoids unnecessary DOM repaints and reflows

2. **Computation Result Caching**

   - Caches date and position calculation results during dragging
   - Only recalculates when mouse position changes
   - Reduces repetitive complex calculations

3. **Simplified Smoothing Algorithm**

   - Optimizes smooth movement algorithm for parent node dragging
   - Reduces complex stop detection and velocity calculations
   - Uses fixed smoothing coefficients to improve performance

4. **CSS Transform Optimization**

   - Uses `transform: translateX()` instead of position recalculation
   - Leverages GPU acceleration to reduce CPU burden
   - Avoids triggering layout reflow

5. **Batch DOM Updates**

   - Combines multiple DOM operations into single updates
   - Uses RAF to manage update timing
   - Reduces page repaint frequency

6. **Event Throttling Optimization**
   - Scroll check frequency reduced to 30fps
   - Data update events use 16ms throttling
   - Balances responsiveness and performance consumption

#### Performance Monitoring Tools

The project includes built-in drag performance testing tools for real-time monitoring:

```javascript
// Enable performance testing in settings
ganttDisplayConfig.enableDragPerformanceTest = true;
```

**Performance Metrics Explanation:**

- **Average FPS > 55**: Excellent, very smooth dragging
- **Average FPS 45-55**: Good, smooth dragging
- **Average FPS 30-45**: Fair, slight delay but acceptable
- **Average FPS < 30**: Needs optimization, noticeable stuttering

#### Configuration Parameters

Performance parameters can be adjusted by modifying `src/config/performance.js`:

```javascript
export const PERFORMANCE_CONFIG = {
  RENDERING: {
    DRAG_THROTTLE: 16, // Drag throttle time(ms) - 60fps
    SCROLL_THROTTLE: 16, // Scroll throttle time(ms)
    BATCH_DELAY: 0, // Batch processing delay
  },
};
```

#### Usage Recommendations

1. **Large Task Count**: Auto-enable virtual scrolling optimization
2. **Low Performance Devices**: Appropriately increase throttle time
3. **High Refresh Rate Displays**: Decrease throttle time for smoother experience
4. **Performance Testing**: Enable performance monitoring in development environment for parameter tuning

## 🎯 Quick Start

### Basic Usage

#### Settings Panel Features

The Gantt chart provides a unified settings panel integrating all major control functions:

- **Date Range Settings**: Customize Gantt chart time range or use auto range
- **Display Settings**: Control Tooltip, overview timeline and other display options
- **Connection Line Settings**: Manage task dependency connection line display and styles
- **Performance Optimization**: Enable/disable auto optimization features
- **Data Operations**: Quick jump to today, add tasks, export data, generate test data

#### Three-level Task Structure

Supports complete three-level task nesting:

- **Level 1**: Project/Module level
- **Level 2**: Feature/Component level
- **Level 3**: Specific tasks/Work items

#### Milestone Tasks

Supports milestone type tasks for marking important time points:

- Set `milestone: true` to create milestone tasks
- Milestone tasks display with special styling in Gantt chart
- Usually used for project important nodes and deliverable markers

```vue
<template>
  <div id="app">
    <GanttChart
      :tasks="tasks"
      :dependencies="dependencies"
      start-date="2024-01-01"
      end-date="2024-12-31"
      :tooltip-enabled="true"
      :tooltip-delay="1000"
    />
  </div>
</template>

<script>
import GanttChart from "./components/GanttChart.vue";

export default {
  components: {
    GanttChart,
  },
  data() {
    return {
      tasks: [
        {
          id: 1,
          name: "Project Planning",
          startDate: "2024-01-01",
          endDate: "2024-01-15",
          progress: 100,
          color: "#3498db",
        },
        {
          id: 2,
          name: "Development",
          startDate: "2024-01-16",
          endDate: "2024-03-15",
          progress: 60,
          color: "#e74c3c",
        },
      ],
      dependencies: [
        {
          id: 1,
          from: 1,
          to: 2,
          type: "finish_to_start",
        },
      ],
    };
  },
};
</script>
```

### Advanced Configuration

#### Task Data Structure

```javascript
const task = {
  id: 1, // Unique identifier
  name: "Task Name", // Task name
  startDate: "2024-01-01", // Start date (YYYY-MM-DD format)
  endDate: "2024-01-15", // End date (YYYY-MM-DD format)
  progress: 50, // Progress percentage (0-100)
  color: "#3498db", // Task color
  type: "task", // Task type: 'task', 'milestone', 'deliverable'
  assignee: "John Doe", // Assignee
  children: [], // Child tasks (for three-level structure)
  milestone: false, // Whether it's a milestone
  editable: true, // Whether editable
  deletable: true, // Whether deletable
};
```

#### Dependency Data Structure

```javascript
const dependency = {
  id: 1, // Unique identifier
  from: 1, // Source task ID
  to: 2, // Target task ID
  type: "finish_to_start", // Dependency type
  color: "#666", // Connection line color
  label: "Depends on", // Connection line label
};
```

#### Dependency Types

Supports all four project dependency types:

- **FS (Finish-To-Start)**: Task B cannot start until Task A finishes
- **SS (Start-To-Start)**: Task B cannot start until Task A starts
- **FF (Finish-To-Finish)**: Task B cannot finish until Task A finishes
- **SF (Start-To-Finish)**: Task B cannot finish until Task A starts

### Component Properties

#### Main Properties

| Property           | Type    | Default | Description                |
| ------------------ | ------- | ------- | -------------------------- |
| `tasks`            | Array   | []      | Task data array            |
| `dependencies`     | Array   | []      | Dependency data array      |
| `start-date`       | String  | auto    | Gantt chart start date     |
| `end-date`         | String  | auto    | Gantt chart end date       |
| `tooltip-enabled`  | Boolean | true    | Enable task tooltips       |
| `tooltip-delay`    | Number  | 1000    | Tooltip display delay (ms) |
| `show-connections` | Boolean | true    | Show dependency lines      |
| `editable`         | Boolean | true    | Enable task editing        |

#### Display Control Properties

| Property                 | Type    | Default | Description                 |
| ------------------------ | ------- | ------- | --------------------------- |
| `show-task-name`         | Boolean | true    | Show task names on bars     |
| `show-progress`          | Boolean | true    | Show progress indicators    |
| `show-progress-handle`   | Boolean | true    | Show progress drag handles  |
| `show-connection-labels` | Boolean | false   | Show dependency line labels |
| `show-milestones`        | Boolean | true    | Show milestone markers      |
| `show-critical-path`     | Boolean | false   | Highlight critical path     |

### Event Handling

#### Task Events

```vue
<GanttChart
  @task-click="handleTaskClick"
  @task-dblclick="handleTaskDoubleClick"
  @task-updated="handleTaskUpdate"
  @task-created="handleTaskCreate"
  @task-deleted="handleTaskDelete"
/>
```

#### Dependency Events

```vue
<GanttChart
  @dependency-created="handleDependencyCreate"
  @dependency-updated="handleDependencyUpdate"
  @dependency-deleted="handleDependencyDelete"
/>
```

### Styling Customization

#### CSS Variables

```css
:root {
  --gantt-primary-color: #3498db;
  --gantt-background-color: #ffffff;
  --gantt-grid-color: #e0e0e0;
  --gantt-text-color: #333333;
  --gantt-milestone-color: #f39c12;
  --gantt-dependency-color: #95a5a6;
}
```

#### Custom Task Styling

```css
.gantt-task-bar {
  border-radius: 4px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

.gantt-task-bar.milestone {
  border-radius: 50%;
  transform: rotate(45deg);
}
```

## 🛠️ Advanced Features

### Connection Line Customization

- **Double-click to Edit**: Double-click any connection line to change color and add labels
- **Smart Routing**: Automatic path calculation to avoid overlapping with tasks
- **Z-shaped Connections**: Professional 4-segment Z-shaped connection algorithm
- **Color Coding**: Different colors for different dependency types

### Performance Features

- **Automatic Optimization**: Enables performance optimizations for large datasets
- **Virtual Scrolling**: Only renders visible items for better performance
- **Smart Caching**: Caches calculated paths and positions
- **RAF Animation**: Uses requestAnimationFrame for smooth animations

### Data Management

- **Auto Save**: Automatically saves changes to localStorage
- **Export/Import**: Export data to JSON or import from external sources
- **Undo/Redo**: Complete undo/redo functionality
- **Data Validation**: Ensures data integrity and prevents conflicts

## 🔧 Configuration

### Performance Configuration

Modify `src/config/performance.js` for performance tuning:

```javascript
export const PERFORMANCE_CONFIG = {
  RENDERING: {
    DRAG_THROTTLE: 16, // Drag throttle (ms)
    SCROLL_THROTTLE: 16, // Scroll throttle (ms)
    MAX_RENDERED_TASKS: 1000, // Maximum rendered tasks
    VIRTUAL_SCROLL_THRESHOLD: 100, // Virtual scroll threshold
  },
  CACHING: {
    ENABLE_PATH_CACHE: true, // Enable path caching
    CACHE_DURATION: 5000, // Cache duration (ms)
  },
};
```

### Feature Configuration

Modify `src/config/features.js` for feature control:

```javascript
export const FEATURE_CONFIG = {
  TASK_TYPES: {
    task: { icon: "📋", color: "#3498db", name: "Task" },
    milestone: { icon: "🎯", color: "#f39c12", name: "Milestone" },
    deliverable: { icon: "📦", color: "#27ae60", name: "Deliverable" },
  },
  DEPENDENCIES: {
    TYPES: ["FS", "SS", "FF", "SF"],
    DEFAULT_COLOR: "#95a5a6",
    EDITABLE: true,
  },
};
```

## 📱 Browser Support

- Chrome (recommended)
- Firefox
- Safari
- Edge

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by dhtmlx Gantt Chart
- Built with Vue.js and Element UI
- Uses modern web technologies for optimal performance

## 📞 Support

For support and questions:

- Create an issue on GitHub
- Check the documentation
- Join our community discussions

---

**Note**: This is a professional Gantt chart component designed for project management applications. It provides enterprise-level features while maintaining ease of use and customization flexibility.

## 🌐 中文文档

For Chinese documentation, please see [README_CN.md](README_CN.md).