iris-gantt 1.0.1 → 1.0.2

package/USAGE.md

@@ -0,0 +1,838 @@
+# iris-gantt Usage Documentation
+
+Complete guide to using the iris-gantt React component library.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Basic Usage](#basic-usage)
+- [Task Management](#task-management)
+- [Dependencies](#dependencies)
+- [Configuration](#configuration)
+- [Advanced Features](#advanced-features)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+- [Common Patterns](#common-patterns)
+- [Troubleshooting](#troubleshooting)
+
+## Installation
+
+### Install the Package
+
+```bash
+npm install iris-gantt
+```
+
+### Install Peer Dependencies
+
+```bash
+npm install react react-dom antd dayjs @fortawesome/react-fontawesome @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons
+```
+
+**Note:** These are required peer dependencies. Make sure they're installed in your project.
+
+## Quick Start
+
+```tsx
+import React from 'react'
+import { Gantt } from 'iris-gantt'
+import 'iris-gantt/gantt.css'
+import type { Task, Link } from 'iris-gantt'
+
+function App() {
+  const tasks: Task[] = [
+    {
+      id: '1',
+      text: 'Project Planning',
+      start: new Date(2024, 0, 1),
+      end: new Date(2024, 0, 15),
+      duration: 14,
+      progress: 100,
+    },
+  ]
+
+  return <Gantt tasks={tasks} />
+}
+```
+
+**Important:** Don't forget to import the CSS file: `import 'iris-gantt/gantt.css'`
+
+## Basic Usage
+
+### Minimal Example
+
+```tsx
+import { Gantt } from 'iris-gantt'
+import 'iris-gantt/gantt.css'
+
+const tasks = [
+  {
+    id: '1',
+    text: 'Task 1',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 0, 10),
+    duration: 9,
+    progress: 50,
+  },
+]
+
+function MyGantt() {
+  return <Gantt tasks={tasks} />
+}
+```
+
+### With Event Handlers
+
+```tsx
+import { Gantt } from 'iris-gantt'
+import 'iris-gantt/gantt.css'
+import type { Task, Link } from 'iris-gantt'
+
+function MyGantt() {
+  const [tasks, setTasks] = useState<Task[]>([])
+  const [links, setLinks] = useState<Link[]>([])
+
+  const handleTaskUpdate = (task: Task) => {
+    setTasks(prev => prev.map(t => t.id === task.id ? task : t))
+    // Or sync with your backend
+    // await updateTask(task)
+  }
+
+  const handleTaskCreate = (task: Task) => {
+    setTasks(prev => [...prev, task])
+    // await createTask(task)
+  }
+
+  const handleTaskDelete = (taskId: string) => {
+    setTasks(prev => prev.filter(t => t.id !== taskId))
+    // await deleteTask(taskId)
+  }
+
+  return (
+    <Gantt
+      tasks={tasks}
+      links={links}
+      onTaskUpdate={handleTaskUpdate}
+      onTaskCreate={handleTaskCreate}
+      onTaskDelete={handleTaskDelete}
+      onLinkCreate={(link) => setLinks(prev => [...prev, link])}
+      onLinkDelete={(linkId) => setLinks(prev => prev.filter(l => l.id !== linkId))}
+    />
+  )
+}
+```
+
+## Task Management
+
+### Creating Tasks
+
+Tasks are created through the built-in task creator (click the "+ Add Task" button) or programmatically:
+
+```tsx
+const newTask: Task = {
+  id: 'unique-id',
+  text: 'Task Name',
+  start: new Date(2024, 0, 1),
+  end: new Date(2024, 0, 10),
+  duration: 9, // days
+  progress: 0, // 0-100
+  type: 'task', // 'task' | 'milestone' | 'project'
+  color: '#4A90E2',
+  owner: 'John Doe',
+  priority: 'high', // 'low' | 'medium' | 'high'
+  details: 'Task description',
+}
+```
+
+### Task Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | ✅ | Unique identifier |
+| `text` | `string` | ✅ | Task name/label |
+| `start` | `Date` | ✅ | Start date |
+| `end` | `Date` | ✅ | End date |
+| `duration` | `number` | ✅ | Duration in days |
+| `progress` | `number` | ✅ | Progress 0-100 |
+| `type` | `'task' \| 'milestone' \| 'project'` | ❌ | Task type |
+| `parent` | `string` | ❌ | Parent task ID (for hierarchy) |
+| `open` | `boolean` | ❌ | Whether parent is expanded |
+| `color` | `string` | ❌ | Hex color code |
+| `owner` | `string` | ❌ | Assigned person |
+| `priority` | `'low' \| 'medium' \| 'high'` | ❌ | Priority level |
+| `details` | `string` | ❌ | Task description |
+| `dependencies` | `string[]` | ❌ | Array of task IDs this depends on |
+| `segments` | `TaskSegment[]` | ❌ | For split tasks |
+
+### Hierarchical Tasks (Parent/Child)
+
+```tsx
+const tasks: Task[] = [
+  {
+    id: '1',
+    text: 'Project',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 2, 31),
+    duration: 90,
+    progress: 30,
+    type: 'project',
+    open: true, // Expanded by default
+  },
+  {
+    id: '2',
+    text: 'Phase 1',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 1, 15),
+    duration: 45,
+    progress: 50,
+    parent: '1', // Child of task '1'
+  },
+  {
+    id: '3',
+    text: 'Phase 2',
+    start: new Date(2024, 1, 16),
+    end: new Date(2024, 2, 31),
+    duration: 45,
+    progress: 10,
+    parent: '1', // Child of task '1'
+  },
+]
+```
+
+### Task Types
+
+```tsx
+// Regular task
+{ type: 'task', ... }
+
+// Milestone (rendered as a diamond)
+{ type: 'milestone', ... }
+
+// Project (summary task, can have children)
+{ type: 'project', ... }
+```
+
+### Split Tasks
+
+Tasks can be split into multiple segments:
+
+```tsx
+const task: Task = {
+  id: '1',
+  text: 'Split Task',
+  start: new Date(2024, 0, 1),
+  end: new Date(2024, 0, 20),
+  duration: 20,
+  progress: 50,
+  segments: [
+    {
+      start: new Date(2024, 0, 1),
+      end: new Date(2024, 0, 10),
+      duration: 9,
+    },
+    {
+      start: new Date(2024, 0, 15),
+      end: new Date(2024, 0, 20),
+      duration: 5,
+    },
+  ],
+}
+```
+
+## Dependencies
+
+### Creating Links
+
+Links define relationships between tasks:
+
+```tsx
+const links: Link[] = [
+  {
+    id: 'l1',
+    source: '1', // Source task ID
+    target: '2', // Target task ID
+    type: 'e2s', // Dependency type
+    lag: 0, // Optional lag time
+    lagUnit: 'day', // 'day' | 'hour' | 'week' | 'month'
+  },
+]
+```
+
+### Dependency Types
+
+| Type | Code | Description |
+|------|------|-------------|
+| End-to-Start | `'e2s'` | Task B starts when Task A ends (most common) |
+| Start-to-Start | `'s2s'` | Tasks start together |
+| End-to-End | `'e2e'` | Tasks end together |
+| Start-to-End | `'s2e'` | Task B ends when Task A starts |
+
+### Example with Dependencies
+
+```tsx
+const tasks: Task[] = [
+  { id: '1', text: 'Design', start: new Date(2024, 0, 1), end: new Date(2024, 0, 10), duration: 9, progress: 100 },
+  { id: '2', text: 'Development', start: new Date(2024, 0, 11), end: new Date(2024, 0, 25), duration: 14, progress: 50 },
+  { id: '3', text: 'Testing', start: new Date(2024, 0, 26), end: new Date(2024, 1, 5), duration: 10, progress: 0 },
+]
+
+const links: Link[] = [
+  { id: 'l1', source: '1', target: '2', type: 'e2s' }, // Development starts after Design
+  { id: 'l2', source: '2', target: '3', type: 'e2s' }, // Testing starts after Development
+]
+```
+
+### Lag Time
+
+Add delays or lead time to dependencies:
+
+```tsx
+const links: Link[] = [
+  {
+    id: 'l1',
+    source: '1',
+    target: '2',
+    type: 'e2s',
+    lag: 2, // 2 days delay
+    lagUnit: 'day',
+  },
+  {
+    id: 'l2',
+    source: '2',
+    target: '3',
+    type: 'e2s',
+    lag: -1, // 1 day lead time (negative = starts early)
+    lagUnit: 'day',
+  },
+]
+```
+
+## Configuration
+
+### Basic Configuration
+
+```tsx
+<Gantt
+  tasks={tasks}
+  config={{
+    theme: 'light', // or 'dark'
+    weekends: true,
+    readonly: false,
+    editable: true,
+  }}
+/>
+```
+
+### Timeline Scales
+
+Customize the timeline display:
+
+```tsx
+import type { Scale } from 'iris-gantt'
+
+const scales: Scale[] = [
+  { unit: 'month', step: 1, format: 'MMM YYYY' },
+  { unit: 'week', step: 1, format: 'W' },
+  { unit: 'day', step: 1, format: 'D' },
+]
+
+<Gantt
+  tasks={tasks}
+  config={{ scales }}
+/>
+```
+
+Available units: `'hour'`, `'day'`, `'week'`, `'month'`, `'quarter'`, `'year'`
+
+### Custom Columns
+
+```tsx
+import type { Column } from 'iris-gantt'
+
+const columns: Column[] = [
+  { name: 'text', label: 'Task', width: 300, align: 'left', resize: true },
+  { name: 'owner', label: 'Owner', width: 150, align: 'left' },
+  { name: 'priority', label: 'Priority', width: 100, align: 'center' },
+  { name: 'duration', label: 'Duration', width: 100, align: 'right' },
+]
+
+<Gantt
+  tasks={tasks}
+  config={{ columns }}
+/>
+```
+
+### Custom Column Templates
+
+```tsx
+const columns: Column[] = [
+  {
+    name: 'status',
+    label: 'Status',
+    width: 120,
+    template: (task) => {
+      if (task.progress === 100) return '✅ Complete'
+      if (task.progress > 0) return '🔄 In Progress'
+      return '⏳ Not Started'
+    },
+  },
+]
+```
+
+### Holidays
+
+```tsx
+<Gantt
+  tasks={tasks}
+  config={{
+    holidays: [
+      new Date(2024, 0, 1), // New Year
+      new Date(2024, 6, 4), // Independence Day
+      new Date(2024, 11, 25), // Christmas
+    ],
+  }}
+/>
+```
+
+### Markers
+
+Add vertical markers to highlight important dates:
+
+```tsx
+import type { Marker } from 'iris-gantt'
+
+const markers: Marker[] = [
+  {
+    id: 'm1',
+    date: new Date(2024, 2, 15),
+    text: 'Release Date',
+    css: 'border-left: 2px solid red;',
+  },
+]
+
+<Gantt
+  tasks={tasks}
+  config={{ markers }}
+/>
+```
+
+### Sizing
+
+```tsx
+<Gantt
+  tasks={tasks}
+  config={{
+    taskHeight: 30, // Height of task bars
+    rowHeight: 44, // Height of each row
+    scaleHeight: 28, // Height of timeline scales
+    columnWidth: 50, // Width of timeline columns
+    minColumnWidth: 30, // Minimum column width
+  }}
+/>
+```
+
+## Advanced Features
+
+### Auto-Scheduling
+
+Automatically schedule tasks based on dependencies:
+
+```tsx
+<Gantt
+  tasks={tasks}
+  links={links}
+  config={{
+    autoSchedule: true,
+  }}
+/>
+```
+
+The toolbar includes an "Auto-Schedule" button that recalculates task dates based on dependencies.
+
+### Critical Path
+
+Highlight the critical path (longest path through dependencies):
+
+```tsx
+<Gantt
+  tasks={tasks}
+  links={links}
+  config={{
+    criticalPath: true,
+  }}
+/>
+```
+
+Critical tasks are highlighted in red.
+
+### Baselines
+
+Track original plans vs. current state:
+
+```tsx
+import { createBaseline } from 'iris-gantt'
+
+// Create baseline from current tasks
+const baseline = createBaseline(tasks)
+
+// Later, compare current tasks to baseline
+<Gantt
+  tasks={currentTasks}
+  config={{
+    baselines: true,
+    // Baselines are stored internally
+  }}
+/>
+```
+
+### Undo/Redo
+
+Built-in undo/redo system (Ctrl+Z / Ctrl+Y):
+
+```tsx
+// No configuration needed - works automatically
+<Gantt tasks={tasks} />
+```
+
+The toolbar includes undo/redo buttons.
+
+### Export
+
+Export your Gantt chart data:
+
+```tsx
+import * as ExportUtils from 'iris-gantt'
+
+// Export to CSV
+const csv = ExportUtils.exportToCSV(tasks, links)
+
+// Export to JSON
+const json = ExportUtils.exportToJSON(tasks, links)
+
+// Export to Excel
+const excel = ExportUtils.exportToExcel(tasks, links)
+```
+
+The toolbar includes an export button with a dropdown menu.
+
+### Filtering and Search
+
+```tsx
+import { FilterSearch, applyFilters, type FilterOptions } from 'iris-gantt'
+
+const [filteredTasks, setFilteredTasks] = useState(tasks)
+const [filters, setFilters] = useState<FilterOptions>({
+  search: '',
+  status: 'all',
+  priority: 'all',
+  owner: '',
+})
+
+// Apply filters
+useEffect(() => {
+  const filtered = applyFilters(tasks, filters)
+  setFilteredTasks(filtered)
+}, [tasks, filters])
+
+<Gantt tasks={filteredTasks} />
+```
+
+## API Reference
+
+### Gantt Component Props
+
+```tsx
+interface GanttProps {
+  tasks: Task[]                    // Required: Array of tasks
+  links?: Link[]                   // Optional: Array of dependency links
+  config?: Partial<GanttConfig>    // Optional: Configuration object
+  onTaskUpdate?: (task: Task) => void
+  onTaskCreate?: (task: Task) => void
+  onTaskDelete?: (taskId: string) => void
+  onLinkCreate?: (link: Link) => void
+  onLinkDelete?: (linkId: string) => void
+}
+```
+
+### GanttConfig
+
+```tsx
+interface GanttConfig {
+  columns?: Column[]
+  scales?: Scale[]
+  readonly?: boolean
+  editable?: boolean
+  taskHeight?: number
+  rowHeight?: number
+  scaleHeight?: number
+  columnWidth?: number
+  minColumnWidth?: number
+  autoSchedule?: boolean
+  criticalPath?: boolean
+  baselines?: boolean
+  markers?: Marker[]
+  weekends?: boolean
+  holidays?: Date[]
+  theme?: 'light' | 'dark'
+  locale?: string
+}
+```
+
+### Task
+
+```tsx
+interface Task {
+  id: string
+  text: string
+  start: Date
+  end: Date
+  duration: number
+  progress: number
+  type?: 'task' | 'milestone' | 'project'
+  parent?: string
+  open?: boolean
+  color?: string
+  details?: string
+  owner?: string
+  priority?: 'low' | 'medium' | 'high'
+  dependencies?: string[]
+  segments?: TaskSegment[]
+}
+```
+
+### Link
+
+```tsx
+interface Link {
+  id: string
+  source: string
+  target: string
+  type: 'e2s' | 's2s' | 'e2e' | 's2e'
+  lag?: number
+  lagUnit?: 'day' | 'hour' | 'week' | 'month'
+}
+```
+
+## Examples
+
+### Complete Example with State Management
+
+```tsx
+import React, { useState } from 'react'
+import { Gantt } from 'iris-gantt'
+import 'iris-gantt/gantt.css'
+import type { Task, Link } from 'iris-gantt'
+
+function ProjectGantt() {
+  const [tasks, setTasks] = useState<Task[]>([
+    {
+      id: '1',
+      text: 'Project Setup',
+      start: new Date(2024, 0, 1),
+      end: new Date(2024, 0, 5),
+      duration: 4,
+      progress: 100,
+      type: 'project',
+      open: true,
+    },
+    {
+      id: '2',
+      text: 'Design Phase',
+      start: new Date(2024, 0, 6),
+      end: new Date(2024, 0, 20),
+      duration: 14,
+      progress: 75,
+      parent: '1',
+      owner: 'Alice',
+      priority: 'high',
+    },
+    {
+      id: '3',
+      text: 'Development',
+      start: new Date(2024, 0, 21),
+      end: new Date(2024, 1, 15),
+      duration: 25,
+      progress: 30,
+      parent: '1',
+      owner: 'Bob',
+      priority: 'high',
+    },
+  ])
+
+  const [links, setLinks] = useState<Link[]>([
+    { id: 'l1', source: '2', target: '3', type: 'e2s' },
+  ])
+
+  return (
+    <div style={{ height: '600px' }}>
+      <Gantt
+        tasks={tasks}
+        links={links}
+        config={{
+          theme: 'light',
+          weekends: true,
+          criticalPath: true,
+          autoSchedule: true,
+        }}
+        onTaskUpdate={(task) => {
+          setTasks(prev => prev.map(t => t.id === task.id ? task : t))
+        }}
+        onTaskCreate={(task) => {
+          setTasks(prev => [...prev, task])
+        }}
+        onTaskDelete={(id) => {
+          setTasks(prev => prev.filter(t => t.id !== id))
+          setLinks(prev => prev.filter(l => l.source !== id && l.target !== id))
+        }}
+        onLinkCreate={(link) => {
+          setLinks(prev => [...prev, link])
+        }}
+        onLinkDelete={(id) => {
+          setLinks(prev => prev.filter(l => l.id !== id))
+        }}
+      />
+    </div>
+  )
+}
+```
+
+### With React Query
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { Gantt } from 'iris-gantt'
+import 'iris-gantt/gantt.css'
+
+function GanttWithBackend() {
+  const queryClient = useQueryClient()
+
+  const { data: tasks = [] } = useQuery({
+    queryKey: ['tasks'],
+    queryFn: () => fetch('/api/tasks').then(r => r.json()),
+  })
+
+  const { data: links = [] } = useQuery({
+    queryKey: ['links'],
+    queryFn: () => fetch('/api/links').then(r => r.json()),
+  })
+
+  const updateTask = useMutation({
+    mutationFn: (task) => fetch(`/api/tasks/${task.id}`, {
+      method: 'PUT',
+      body: JSON.stringify(task),
+    }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['tasks'] })
+    },
+  })
+
+  return (
+    <Gantt
+      tasks={tasks}
+      links={links}
+      onTaskUpdate={(task) => updateTask.mutate(task)}
+    />
+  )
+}
+```
+
+## Common Patterns
+
+### Controlled Component Pattern
+
+```tsx
+const [tasks, setTasks] = useState(initialTasks)
+
+<Gantt
+  tasks={tasks}
+  onTaskUpdate={(task) => {
+    // Update local state
+    setTasks(prev => prev.map(t => t.id === task.id ? task : t))
+    // Sync with backend
+    updateTaskInBackend(task)
+  }}
+/>
+```
+
+### Read-Only Mode
+
+```tsx
+<Gantt
+  tasks={tasks}
+  config={{ readonly: true }}
+/>
+```
+
+### Custom Styling
+
+The component uses CSS variables that you can override:
+
+```css
+.gantt-container {
+  --wx-gantt-primary: #your-color;
+  --gantt-row-height: 50px;
+  /* etc. */
+}
+```
+
+## Troubleshooting
+
+### CSS Not Loading
+
+**Problem:** Styles are not applied.
+
+**Solution:** Make sure you import the CSS:
+```tsx
+import 'iris-gantt/gantt.css'
+```
+
+### Tasks Not Rendering
+
+**Problem:** Tasks don't appear on the chart.
+
+**Solution:** 
+- Check that `start` and `end` are `Date` objects, not strings
+- Verify `duration` is a positive number
+- Ensure tasks are within the visible date range
+
+### TypeScript Errors
+
+**Problem:** Type errors when using the component.
+
+**Solution:** Import types explicitly:
+```tsx
+import type { Task, Link, GanttProps } from 'iris-gantt'
+```
+
+### Dependencies Not Showing
+
+**Problem:** Dependency arrows don't appear.
+
+**Solution:**
+- Ensure `links` array is provided
+- Check that `source` and `target` IDs match task IDs
+- Verify tasks exist for all link references
+
+### Date Format Issues
+
+**Problem:** Dates are incorrect or not displaying.
+
+**Solution:** Always use `Date` objects, not strings:
+```tsx
+// ✅ Correct
+start: new Date(2024, 0, 1)
+
+// ❌ Wrong
+start: '2024-01-01'
+```
+
+## Additional Resources
+
+- [GitHub Repository](https://github.com/TimJerry725/ganttchart)
+- [API Reference](./README.md)
+- [Publishing Guide](./PUBLISHING.md)
+
+---
+
+**Need Help?** Open an issue on GitHub or check the examples in the Storybook demos.