@cloudgpt/timeline-editor/README.md

Enhanced React timeline editor with advanced features including theme system, max duration controls, cursor customization, handle styling, and media support for video editing applications.

# @cloudgpt/timeline-editor

[![npm version](https://img.shields.io/npm/v/@cloudgpt/timeline-editor.svg?style=flat-square)](https://www.npmjs.com/package/@cloudgpt/timeline-editor)
[![npm downloads](https://img.shields.io/npm/dm/@cloudgpt/timeline-editor.svg?style=flat-square)](https://www.npmjs.com/package/@cloudgpt/timeline-editor)

**Enhanced React Timeline Editor** - A powerful and feature-rich timeline editor component for building video editing applications, animation tools, and media timeline interfaces.

## ✨ Key Features

- 🎨 **Advanced Theme System** - Dark, Light, and Ocean themes with full customization
- ⏱️ **Max Duration Control** - Set timeline limits and validate action boundaries
- 🎯 **Custom Cursor Styling** - Full control over cursor appearance and behavior
- 🎛️ **Professional Handles** - Pill-shaped resize handles with gradient effects
- 🎬 **Video Frame Support** - Extract and display video frames on timeline
- 🖼️ **Image Strip Display** - Tiled image previews for visual actions
- 📐 **Grid Snapping** - Precise alignment and positioning
- 🎮 **Drag Line Assistance** - Visual guides for better UX
- 🚀 **Performance Optimized** - Smooth animations and interactions
- 📱 **Responsive Design** - Works across different screen sizes

## 🚀 Installation

```bash
npm install @cloudgpt/timeline-editor
```

## 📖 Basic Usage

```tsx
import { Timeline, TimelineEffect, TimelineRow } from '@cloudgpt/timeline-editor';
import React, { useState } from 'react';

const mockData: TimelineRow[] = [
  {
    id: "0",
    actions: [
      {
        id: "action00",
        start: 0,
        end: 2,
        effectId: "effect0",
      },
    ],
  },
  {
    id: "1", 
    actions: [
      {
        id: "action10",
        start: 1.5,
        end: 5,
        effectId: "effect1",
      }
    ],
  }
];

const mockEffect: Record<string, TimelineEffect> = {
  effect0: {
    id: "effect0",
    name: "Video Clip",
  },
  effect1: {
    id: "effect1", 
    name: "Audio Track",
  },
};

const TimelineEditor = () => {
  const [data, setData] = useState(mockData);
  
  return (
    <Timeline
      editorData={data}
      effects={mockEffect}
      onChange={setData}
      maxDuration={30} // Limit timeline to 30 seconds
      theme={{
        backgroundColor: '#191b1d',
        foregroundColor: '#ffffff',
        cursorColor: '#ff6b35',
      }}
      cursor={{
        cursorColor: '#ff6b35',
        cursorWidth: 2,
        cursorStyle: 'solid',
        showCursorHead: true,
      }}
      handles={{
        showHandles: true,
        handleOpacity: 0.3,
        handleHoverOpacity: 1,
      }}
      style={{ width: '100%', height: 400 }}
    />
  );
};
```

## 🎨 Advanced Features

### Theme Configuration
```tsx
const themeConfig = {
  backgroundColor: '#1a1a1a',
  foregroundColor: '#ffffff', 
  gridColor: 'rgba(255, 255, 255, 0.1)',
  actionBackgroundColor: '#2f3134',
  actionBorderColor: 'rgba(255, 255, 255, 0.2)',
  dragLineColor: '#ff6b35',
};

<Timeline theme={themeConfig} />
```

### Max Duration Control
```tsx
<Timeline
  maxDuration={60} // Limit to 60 seconds
  validateActionChange={({ action, row, start, end }) => {
    // Custom validation logic
    return end <= 60 && start >= 0;
  }}
/>
```

### Custom Cursor Styling
```tsx
const cursorConfig = {
  cursorColor: '#00ff88',
  cursorWidth: 3,
  cursorStyle: 'dashed',
  cursorOpacity: 0.8,
  showCursorHead: true,
  cursorShadow: '0 0 10px rgba(0,255,136,0.5)',
};

<Timeline cursor={cursorConfig} />
```

### Handle Customization
```tsx
const handleConfig = {
  showHandles: true,
  handleBackground: 'linear-gradient(180deg, #ff6b35, #ff4500)',
  handleBorderColor: 'rgba(255, 255, 255, 0.4)',
  handleOpacity: 0.4,
  handleHoverOpacity: 1,
};

<Timeline handles={handleConfig} />
```

## 🎬 Media Support

The enhanced timeline editor supports video frame extraction and image previews:

```tsx
// Custom render function for media actions
const renderAction = (action, row) => {
  if (action.effectId === 'video') {
    return <VideoStrip src="/video/sample.mp4" start={action.start} end={action.end} />;
  }
  if (action.effectId === 'image') {
    return <ImageStrip src="/images/sample.jpg" start={action.start} end={action.end} />;
  }
  return null;
};

<Timeline getActionRender={renderAction} />
```

## 📚 Enhanced from Original

This package is an enhanced version of the original `@xzdarcy/react-timeline-editor` with significant improvements:

- **Enhanced Type System** - Better TypeScript support with comprehensive interfaces
- **Advanced Styling** - Professional-grade visual design and theming
- **Better Performance** - Optimized rendering and interaction handling  
- **Extended API** - More configuration options and customization capabilities
- **Bug Fixes** - Resolved cursor stuttering and validation issues
- **Modern Features** - Support for modern React patterns and hooks

## 🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

Based on the excellent work by [@xzdarcy](https://github.com/xzdarcy) on the original react-timeline-editor.