npm package: @harlock_/scheduler
Description: A flexible and customizable React timeline scheduler component with drag-and-drop, zoom, and i18n support
Author: Your Name
Latest version: 1.0.7

# @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

```bash
npm install @harlock_/scheduler
```

### Peer Dependencies

Make sure you have the following peer dependencies installed:

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

## Quick Start

```jsx
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.

```javascript
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

```javascript
{
  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,
  authorizations?: {
    move?: boolean, // Override global move permission
    resize?: boolean // Override global resize permission
  }
}
```

## License

MIT