iris-gantt 1.5.8 → 1.5.9

package/CUSTOMIZATION_GUIDE.md

@@ -0,0 +1,392 @@
+# UI Customization Guide
+
+Complete guide to customizing all text, labels, and buttons in the Gantt component.
+
+## Overview
+
+The `uiConfig` prop allows you to:
+- ✅ Customize all text labels and placeholders
+- ✅ Show/hide any button with boolean props
+- ✅ Customize tooltips
+- ✅ Customize modal titles and button text
+- ✅ Customize form labels and validation messages
+
+## Basic Usage
+
+```tsx
+import { Gantt } from 'iris-gantt'
+import 'iris-gantt/gantt.css'
+import type { GanttUIConfig } from 'iris-gantt'
+
+const uiConfig: Partial<GanttUIConfig> = {
+  headerTitle: 'My Project Timeline',
+  showHeader: true,
+  showAddTaskButton: true,
+  showBaselineButton: false,
+  addTaskButtonText: 'Add New Task',
+}
+
+function App() {
+  return (
+    <Gantt
+      tasks={tasks}
+      uiConfig={uiConfig}
+    />
+  )
+}
+```
+
+## Complete UI Configuration
+
+### Header
+
+```tsx
+{
+  headerTitle?: string        // Default: 'Iris Gantt'
+  showHeader?: boolean         // Default: true
+}
+```
+
+### Toolbar Buttons (Show/Hide)
+
+```tsx
+{
+  showAddTaskButton?: boolean      // Default: true
+  showBaselineButton?: boolean     // Default: true
+  showZoomButtons?: boolean        // Default: true
+  showExportButtons?: boolean      // Default: true
+  showFilterSearch?: boolean       // Default: true
+}
+```
+
+### Toolbar Button Labels
+
+```tsx
+{
+  addTaskButtonText?: string           // Default: 'New Task'
+  baselineButtonText?: string          // Default: 'Set Baseline'
+  baselineButtonTextActive?: string    // Default: 'Baselines'
+  zoomOutTooltip?: string              // Default: 'Zoom Out'
+  zoomInTooltip?: string               // Default: 'Zoom In'
+  resetZoomTooltip?: string            // Default: 'Reset Zoom'
+  exportCSVTooltip?: string            // Default: 'Export to CSV'
+  exportExcelTooltip?: string          // Default: 'Export to Excel'
+  exportJSONTooltip?: string           // Default: 'Export to JSON'
+  exportPDFTooltip?: string            // Default: 'Export to PDF'
+  hideBaselinesTooltip?: string        // Default: 'Hide Baselines'
+  showBaselinesTooltip?: string        // Default: 'Show Baselines'
+}
+```
+
+### Task Creator Modal
+
+```tsx
+{
+  taskCreatorTitle?: string            // Default: 'Create New Task'
+  taskCreatorOkText?: string           // Default: 'Create Task'
+  taskCreatorCancelText?: string      // Default: 'Cancel'
+  taskNameLabel?: string               // Default: 'Task Name'
+  taskNamePlaceholder?: string         // Default: 'Enter task name'
+  typeLabel?: string                   // Default: 'Type'
+  priorityLabel?: string               // Default: 'Priority'
+  startDateLabel?: string              // Default: 'Start Date'
+  durationLabel?: string               // Default: 'Duration (days)'
+  colorLabel?: string                  // Default: 'Color'
+  progressLabel?: string               // Default: 'Progress (%)'
+  ownerLabel?: string                  // Default: 'Owner'
+  ownerPlaceholder?: string            // Default: 'Assign to...'
+  detailsLabel?: string                // Default: 'Details'
+  detailsPlaceholder?: string         // Default: 'Add task description...'
+  taskNameRequired?: string            // Default: 'Please enter task name'
+}
+```
+
+### Task Type & Priority Options
+
+```tsx
+{
+  taskTypeOptions?: {
+    task?: string          // Default: 'Task'
+    milestone?: string     // Default: 'Milestone'
+    project?: string       // Default: 'Project'
+  },
+  priorityOptions?: {
+    low?: string           // Default: 'Low'
+    medium?: string       // Default: 'Medium'
+    high?: string         // Default: 'High'
+  }
+}
+```
+
+### Task Editor Modal
+
+```tsx
+{
+  taskEditorTitle?: string              // Default: 'Edit Task'
+  taskEditorSaveText?: string          // Default: 'Save Changes'
+  taskEditorCancelText?: string        // Default: 'Cancel'
+  taskEditorDeleteText?: string        // Default: 'Delete'
+  deleteConfirmTitle?: string          // Default: 'Delete Task'
+  deleteConfirmContent?: string        // Default: 'This action cannot be undone.'
+  deleteConfirmOkText?: string         // Default: 'Yes, Delete'
+  deleteConfirmCancelText?: string     // Default: 'No'
+}
+```
+
+### Filter Search
+
+```tsx
+{
+  searchPlaceholder?: string           // Default: 'Search tasks...'
+  allOwnersText?: string               // Default: 'All Owners'
+  allStatusText?: string               // Default: 'All Status'
+  allPriorityText?: string            // Default: 'All Priority'
+  clearFiltersText?: string            // Default: 'Clear'
+  statusOptions?: {
+    all?: string                       // Default: 'All Status'
+    notStarted?: string               // Default: 'Not Started'
+    inProgress?: string               // Default: 'In Progress'
+    completed?: string                 // Default: 'Completed'
+  },
+  priorityFilterOptions?: {
+    all?: string                       // Default: 'All Priority'
+    low?: string                      // Default: 'Low'
+    medium?: string                   // Default: 'Medium'
+    high?: string                     // Default: 'High'
+  }
+}
+```
+
+### Column Labels
+
+```tsx
+{
+  columnLabels?: {
+    name?: string                      // Default: 'Name'
+    dependsOn?: string                  // Default: 'Depends on'
+    duration?: string                   // Default: 'Duration'
+    start?: string                      // Default: 'Start'
+  }
+}
+```
+
+## Examples
+
+### Example 1: Hide All Buttons Except Add Task
+
+```tsx
+<Gantt
+  tasks={tasks}
+  uiConfig={{
+    showBaselineButton: false,
+    showZoomButtons: false,
+    showExportButtons: false,
+    showFilterSearch: false,
+    addTaskButtonText: 'Add Task',
+  }}
+/>
+```
+
+### Example 2: Customize All Text
+
+```tsx
+<Gantt
+  tasks={tasks}
+  uiConfig={{
+    headerTitle: 'Project Timeline',
+    addTaskButtonText: 'Create Task',
+    baselineButtonText: 'Save Baseline',
+    taskCreatorTitle: 'New Task',
+    taskNameLabel: 'Task Title',
+    taskNamePlaceholder: 'Enter task title',
+    typeLabel: 'Task Type',
+    priorityLabel: 'Priority Level',
+  }}
+/>
+```
+
+### Example 3: Internationalization (i18n)
+
+```tsx
+const frenchUIConfig: Partial<GanttUIConfig> = {
+  headerTitle: 'Diagramme de Gantt',
+  addTaskButtonText: 'Nouvelle Tâche',
+  baselineButtonText: 'Définir la Baseline',
+  taskCreatorTitle: 'Créer une Nouvelle Tâche',
+  taskNameLabel: 'Nom de la Tâche',
+  taskNamePlaceholder: 'Entrez le nom de la tâche',
+  typeLabel: 'Type',
+  priorityLabel: 'Priorité',
+  startDateLabel: 'Date de Début',
+  durationLabel: 'Durée (jours)',
+  progressLabel: 'Progression (%)',
+  ownerLabel: 'Responsable',
+  detailsLabel: 'Détails',
+  taskTypeOptions: {
+    task: 'Tâche',
+    milestone: 'Jalon',
+    project: 'Projet',
+  },
+  priorityOptions: {
+    low: 'Faible',
+    medium: 'Moyenne',
+    high: 'Élevée',
+  },
+}
+
+<Gantt tasks={tasks} uiConfig={frenchUIConfig} />
+```
+
+### Example 4: Minimal UI (Hide Everything)
+
+```tsx
+<Gantt
+  tasks={tasks}
+  uiConfig={{
+    showHeader: false,
+    showAddTaskButton: false,
+    showBaselineButton: false,
+    showZoomButtons: false,
+    showExportButtons: false,
+    showFilterSearch: false,
+  }}
+/>
+```
+
+### Example 5: Custom Button Text Only
+
+```tsx
+<Gantt
+  tasks={tasks}
+  uiConfig={{
+    addTaskButtonText: '➕ Add',
+    baselineButtonText: '📅 Baseline',
+    zoomOutTooltip: 'Zoomer',
+    zoomInTooltip: 'Dézoomer',
+  }}
+/>
+```
+
+## Complete Example
+
+```tsx
+import { Gantt } from 'iris-gantt'
+import 'iris-gantt/gantt.css'
+import type { GanttUIConfig } from 'iris-gantt'
+
+function MyGantt() {
+  const uiConfig: Partial<GanttUIConfig> = {
+    // Header
+    headerTitle: 'My Project',
+    showHeader: true,
+
+    // Buttons visibility
+    showAddTaskButton: true,
+    showBaselineButton: true,
+    showZoomButtons: true,
+    showExportButtons: true,
+    showFilterSearch: true,
+
+    // Button labels
+    addTaskButtonText: 'Add Task',
+    baselineButtonText: 'Baseline',
+    baselineButtonTextActive: 'Hide Baseline',
+
+    // Tooltips
+    zoomOutTooltip: 'Zoom Out',
+    zoomInTooltip: 'Zoom In',
+    resetZoomTooltip: 'Reset',
+    exportCSVTooltip: 'Export CSV',
+    exportExcelTooltip: 'Export Excel',
+    exportJSONTooltip: 'Export JSON',
+    exportPDFTooltip: 'Export PDF',
+
+    // Task Creator
+    taskCreatorTitle: 'Create Task',
+    taskCreatorOkText: 'Create',
+    taskCreatorCancelText: 'Cancel',
+    taskNameLabel: 'Task Name',
+    taskNamePlaceholder: 'Enter name',
+    typeLabel: 'Type',
+    priorityLabel: 'Priority',
+    startDateLabel: 'Start',
+    durationLabel: 'Duration',
+    colorLabel: 'Color',
+    progressLabel: 'Progress',
+    ownerLabel: 'Owner',
+    ownerPlaceholder: 'Assign to',
+    detailsLabel: 'Description',
+    detailsPlaceholder: 'Add description',
+
+    // Options
+    taskTypeOptions: {
+      task: 'Task',
+      milestone: 'Milestone',
+      project: 'Project',
+    },
+    priorityOptions: {
+      low: 'Low',
+      medium: 'Medium',
+      high: 'High',
+    },
+
+    // Task Editor
+    taskEditorTitle: 'Edit Task',
+    taskEditorSaveText: 'Save',
+    taskEditorCancelText: 'Cancel',
+    taskEditorDeleteText: 'Delete',
+    deleteConfirmTitle: 'Confirm Delete',
+    deleteConfirmContent: 'Are you sure?',
+    deleteConfirmOkText: 'Delete',
+    deleteConfirmCancelText: 'Cancel',
+
+    // Filters
+    searchPlaceholder: 'Search...',
+    allOwnersText: 'All',
+    clearFiltersText: 'Clear',
+    statusOptions: {
+      all: 'All',
+      notStarted: 'Not Started',
+      inProgress: 'In Progress',
+      completed: 'Done',
+    },
+  }
+
+  return (
+    <Gantt
+      tasks={tasks}
+      links={links}
+      uiConfig={uiConfig}
+      onTaskUpdate={(task) => console.log('Updated:', task)}
+    />
+  )
+}
+```
+
+## TypeScript Support
+
+All UI config options are fully typed:
+
+```tsx
+import type { GanttUIConfig } from 'iris-gantt'
+
+const uiConfig: Partial<GanttUIConfig> = {
+  // TypeScript will autocomplete all available options
+  headerTitle: 'My Gantt',
+  showAddTaskButton: true,
+  // ...
+}
+```
+
+## Notes
+
+- All props are **optional** - if not provided, defaults are used
+- Use `Partial<GanttUIConfig>` to only specify what you need
+- Boolean props default to `true` (buttons shown by default)
+- Text props default to English labels
+- You can mix and match - only customize what you need
+
+## See Also
+
+- [USAGE.md](./USAGE.md) - Complete usage documentation
+- [README.md](./README.md) - Quick start guide

package/DATE_FORMATTING_GUIDE.md

@@ -0,0 +1,121 @@
+# Date Formatting Guide - Iris Gantt
+
+You can customize the date formats in the timeline header (calendar header) using the `scales` property within the `config` object.
+
+For multi-view calendars, use `config.timelineViewScales` to define separate formats for `day`, `week`, and `month` views.
+
+Related header controls:
+- `config.showTimelineHeader` hides the entire timeline header.
+- `showMonthHeading` and `showRangeHeading` can be passed as top-level props or inside `config`.
+- `relativeDayNumbering` can be passed as a top-level prop or inside `config`.
+
+## Available Date Tokens
+These tokens can be used in your format strings:
+
+| Token | Description | Example |
+| :--- | :--- | :--- |
+| `MMMM` | Full Month Name | January, February... |
+| `MMM` | Short Month Name | Jan, Feb... |
+| `MM` | Padded Month Number | 01, 02... |
+| `M` | Month Number | 1, 2... |
+| `DD` | Padded Day Number | 01, 02... |
+| `D` | Day Number | 1, 2... |
+| `YYYY` | Full Year | 2024, 2025... |
+| `YY` | Two-digit Year | 24, 25... |
+| `dddd` | Full Day of Week | Monday, Tuesday... |
+| `HH` | Padded Hour (24h) | 09, 13... |
+| `mm` | Padded Minutes | 05, 30... |
+
+---
+
+## Implementation Examples
+
+### 1. Using Full Month Names
+If you want the top row to show the full month name:
+
+```tsx
+<Gantt
+  tasks={tasks}
+  config={{
+    scales: [
+      { unit: 'month', step: 1, format: 'MMMM YYYY' }, // Output: "January 2024"
+      { unit: 'day', step: 1, format: 'D' }           // Output: "1", "2", "3"...
+    ]
+  }}
+/>
+```
+
+### 2. Using Month Numbers
+If you prefer numbers for the months instead of names:
+
+```tsx
+<Gantt
+  tasks={tasks}
+  config={{
+    scales: [
+      { unit: 'month', step: 1, format: 'MM/YYYY' }, // Output: "01/2024"
+      { unit: 'day', step: 1, format: 'D' }
+    ]
+  }}
+/>
+```
+
+### 3. Relative Day Numbering
+If you want relative numbers (e.g., Day 1, Day 2, Day 3 starting from the project start), use the `relativeDayNumbering` flag:
+
+```tsx
+<Gantt
+  tasks={tasks}
+  config={{
+    relativeDayNumbering: true, // This overrides the 'day' unit format to 1, 2, 3...
+    scales: [
+      { unit: 'month', step: 1, format: 'MMMM' },
+      { unit: 'day', step: 1 }
+    ]
+  }}
+/>
+```
+
+### 4. Customizing per View
+If you are using the Timeline View Switcher, you can customize formats for each view (Day, Week, Month):
+
+```tsx
+<Gantt
+  tasks={tasks}
+  config={{
+    timelineViewScales: {
+      day: [
+        { unit: 'month', step: 1, format: 'MMMM' },
+        { unit: 'day', step: 1, format: 'D' }
+      ],
+      week: [
+        { unit: 'month', step: 1, format: 'MMM' },
+        { unit: 'week', step: 1, format: 'Week W' } // 'W' is a special token for Week of Month
+      ],
+      month: [
+        { unit: 'year', step: 1, format: 'YYYY' },
+        { unit: 'month', step: 1, format: 'MMM' }
+      ]
+    }
+  }}
+/>
+```
+
+### 5. Hiding Header Rows
+If you want to keep custom date formats but hide specific header rows:
+
+```tsx
+<Gantt
+  tasks={tasks}
+  showMonthHeading={false}
+  showRangeHeading={false}
+  config={{
+    showTimelineHeader: true,
+    timelineViewScales: {
+      day: [{ unit: 'day', step: 1, format: 'D' }],
+      week: [{ unit: 'week', step: 1, format: 'Week W' }],
+      month: [{ unit: 'month', step: 1, format: 'MMM YYYY' }]
+    }
+  }}
+/>
+```

package/PACKAGE_SETUP.md

@@ -128,6 +128,8 @@ import 'iris-gantt/gantt.css'
 - **[README.md](./README.md)** - Main documentation
 - **[USAGE.md](./USAGE.md)** - Complete usage guide with all props
 - **[QUICK_START.md](./QUICK_START.md)** - Quick start guide
+- **[PROPS_REFERENCE.md](./PROPS_REFERENCE.md)** - Exported props and TypeScript types
+- **[DATE_FORMATTING_GUIDE.md](./DATE_FORMATTING_GUIDE.md)** - Timeline header date tokens and formatting examples
 - **[RESPONSIVE_STYLING.md](./RESPONSIVE_STYLING.md)** - Responsive design guide
 - **[CUSTOMIZATION_GUIDE.md](./CUSTOMIZATION_GUIDE.md)** - Advanced customization
 
@@ -194,4 +196,5 @@ The package is now:
 
 1. Build the package: `npm run build`
 2. Test locally: `npm link` in package, `npm link iris-gantt` in your project
-3. Publish to npm: `npm publish`
+3. Review packaged docs including `DATE_FORMATTING_GUIDE.md` and `PROPS_REFERENCE.md`
+4. Publish to npm: `npm publish`