@harlock_/scheduler

A flexible and customizable React timeline scheduler component with drag-and-drop functionality, multi-level zoom, internationalization support, and advanced navigation controls.

Features

• 🎯 Drag & Drop: Move and resize timeline items
• 🔍 Multi-Level Zoom: From monthly view down to minute-level granularity
• 🎮 Navigation Controls: Built-in UI controls, keyboard shortcuts, and drag-to-pan
• 🌍 Internationalization: Built-in support for multiple languages (EN, FR, AR)
• 🎨 Customizable: Extensive configuration options for styling, behavior, and visibility
• 📊 Progress Tracking: Display completion percentages on items
• 📅 Special Days: Highlight weekends and special dates (holidays, events)
• 🔒 Authorization Controls: Enable/disable drag, resize, and other operations
• ⚡ Performance: Optimized for large datasets

Installation

npm install @harlock_/scheduler

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install react react-dom @mui/material @emotion/react @emotion/styled dnd-timeline date-fns i18next react-i18next

Quick Start

import React, { useState } from 'react';
import { TimelineContext } from 'dnd-timeline';
import { Timeline, TimelineControls, TIMELINE_CONFIG } from '@harlock_/scheduler';
import { startOfDay, endOfDay } from 'date-fns';

// Optional: Configure global settings
TIMELINE_CONFIG.language = 'en';
TIMELINE_CONFIG.controls = { visible: true, size: 'small' };

function App() {
  const [range, setRange] = useState({
    start: startOfDay(new Date()).getTime(),
    end: endOfDay(new Date()).getTime(),
  });

  const rows = [
    { id: 'row-1', title: 'Resource 1', description: 'Description' },
    { id: 'row-2', title: 'Resource 2', description: 'Description' }
  ];

  const items = [
    {
      id: 'item-1',
      rowId: 'row-1',
      span: { start: Date.now(), end: Date.now() + 3600000 },
      title: 'Task 1',
      color: '#3b82f6',
      completion: 50
    }
  ];

  // Navigation Handlers
  const handleZoom = (direction) => {
    setRange((prev) => {
      const duration = prev.end - prev.start;
      const center = prev.start + duration / 2;
      const newDuration = direction === 'in' ? duration * 0.8 : duration * 1.2;
      return {
        start: center - newDuration / 2,
        end: center + newDuration / 2,
      };
    });
  };

  const handlePan = (direction) => {
    setRange((prev) => {
      const duration = prev.end - prev.start;
      const shift = duration * 0.1;
      return {
        start: direction === 'left' ? prev.start - shift : prev.start + shift,
        end: direction === 'left' ? prev.end - shift : prev.end + shift,
      };
    });
  };

  return (
    <div style={{ height: '500px', position: 'relative' }}>
      <TimelineContext range={range} onRangeChanged={setRange}>
        <Timeline items={items} rows={rows} onRangeChange={setRange} />
        <TimelineControls 
          onZoomIn={() => handleZoom('in')}
          onZoomOut={() => handleZoom('out')}
          onPanLeft={() => handlePan('left')}
          onPanRight={() => handlePan('right')}
        />
      </TimelineContext>
    </div>
  );
}

Configuration

The component is highly configurable via the TIMELINE_CONFIG object. You can modify these settings globally.

import { TIMELINE_CONFIG } from '@harlock_/scheduler';

// 1. General Settings
TIMELINE_CONFIG.language = 'en'; // 'en', 'fr', 'ar'
TIMELINE_CONFIG.rowHeight = 60;
TIMELINE_CONFIG.showCompletion = true;
TIMELINE_CONFIG.showExceptions = true; // Show warning icon for items with exceptions

// 2. Navigation Controls
TIMELINE_CONFIG.controls = {
  visible: true, // Show/hide floating controls
  size: "medium" // "small", "medium", "large"
};

// 3. Authorization
TIMELINE_CONFIG.authorizations = {
  canMoveItems: true,
  canResizeItems: true
};

// 4. Weekend Highlighting
TIMELINE_CONFIG.weekends = {
  enabled: true,
  days: [6, 7], // Saturday, Sunday
  backgroundColor: "#eff6ff",
  showColumnBackgrounds: true
};

// 5. Special Days (Holidays, etc.)
TIMELINE_CONFIG.specialDays = {
  enabled: true,
  showColumnBackgrounds: true,
  dates: [
    { date: "2025-12-25", description: "Christmas", backgroundColor: "#fef3c7" },
    { date: "2025-01-01", description: "New Year", backgroundColor: "#fce7f3" }
  ]
};

// 6. Typography
TIMELINE_CONFIG.title.fontSize = 14;
TIMELINE_CONFIG.title.fontWeight = 600;

Navigation Features

UI Controls

The TimelineControls component provides floating buttons for:

• Zoom In / Out
• Pan Left / Right

Keyboard Shortcuts

• Arrow Left / Right: Pan timeline
• + / -: Zoom in / out

Drag-to-Pan

Click and drag anywhere on the empty background of the timeline to pan the view.

API Reference

Timeline Component

Props:

• items (array): Array of item objects
• rows (array): Array of row objects
• onRangeChange (function): Callback when drag-to-pan updates the range

Item Object Structure

{
  id: string,
  rowId: string,
  span: { start: number, end: number },
  title?: string,
  subtitle?: string,
  description?: string,
  color?: string,
  completion?: number,
  exceptions?: array, // Triggers warning icon if showExceptions is true
  disabled?: boolean
}

License

MIT