fleeta-components/README.md

A comprehensive React component library for fleet management applications

# 🚀 FleetA VideoPlayer

[![npm version](https://badge.fury.io/js/fleeta-components.svg)](https://badge.fury.io/js/fleeta-components)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18%2B-blue)](https://reactjs.org/)
[![Tree Shaking](https://img.shields.io/badge/Tree%20Shaking-✅-green)](#tree-shaking)

A comprehensive React component library for fleet management applications. Features video player, GPS tracking, sensor data visualization, and extensible components for fleet operations.

## 🚀 Quick Start

### Installation

```bash
npm install fleeta-components
```

### Peer Dependencies

Install required peer dependencies:

```bash
npm install react react-dom mapbox-gl react-map-gl
```

### Basic Usage

```tsx
import React from 'react';
import { VideoPlayer } from 'fleeta-components';
import 'fleeta-components/dist/style.css';

function App() {
  return (
    <div style={{ width: '100%', height: '600px' }}>
      <VideoPlayer
        videoUrl="https://example.com/dashcam-video.mp4"
        enableMetadataParsing={true}
        showMap={true}
        autoPlay={true}
      />
    </div>
  );
}
```

## ✨ Features

### 🎬 VideoPlayer Module

Complete video playback solution with integrated components:
- **VideoPlayer** - Main video player with controls
- **MapComponent** - GPS tracking and route visualization  
- **EventComponent** - G-sensor data visualization

- 🎬 **Video Player Component** - Advanced video player with GPS and sensor integration
- 🗺️ **GPS Tracking** - Real-time vehicle position tracking on interactive maps
- 📊 **G-Sensor Visualization** - Live acceleration data display
- 🔍 **MP4 Metadata Parsing** - Automatic extraction of GPS and sensor data
- 🚗 **Fleet Components** - Extensible component library for fleet management
- 🎨 **Customizable UI** - Dark/light mode and flexible styling
- 📱 **Responsive Design** - Works on desktop and mobile devices
- 🌳 **Tree Shaking** - Import only what you need
- 🔒 **TypeScript** - Full type safety and excellent DX

## 🔧 Environment Setup

Set up Mapbox for map functionality:

```bash
# .env file
VITE_MAPBOX_ACCESS_TOKEN=your_mapbox_token_here
```

## 📖 Documentation

- [Installation Guide](./docs/INSTALLATION.md)
- [API Documentation](./docs/API.md)
- [Usage Examples](./docs/EXAMPLES.md)
- [Troubleshooting](./docs/TROUBLESHOOTING.md)

## 🌳 Tree Shaking

Import only what you need to reduce bundle size:

```tsx
// Import VideoPlayer with all integrated components
import { VideoPlayer } from 'fleeta-components';

// Import specific utilities only
import { parseGpsData } from 'fleeta-components';

// Import only types (zero runtime cost)
import type { VideoPlayerProps } from 'fleeta-components';
```

## 📖 Documentation

- [Installation Guide](./docs/INSTALLATION.md)
- [API Documentation](./docs/API.md)
- [Usage Examples](./docs/EXAMPLES.md)
- [Troubleshooting](./docs/TROUBLESHOOTING.md)

## 🎯 Complete VideoPlayer Solution

The VideoPlayer component includes all necessary sub-components:

```tsx
// Import specific components
import { VideoPlayer } from 'fleeta-components';

// Import specific utilities
import { parseGpsData } from 'fleeta-components';

// Import only types (zero runtime cost)
import type { VideoPlayerProps } from 'fleeta-components';
```

### Components

#### VideoPlayer

The main video player component with integrated GPS mapping and sensor data visualization.

```tsx
interface VideoPlayerProps {
  // Video source and configuration
  videoUrl: string | null;
  
  enableMetadataParsing?: boolean;
  showMap?: boolean;
  
  // GPS and sensor data (external)
  gpsPoints?: GpsPoint[] | null;
  sensorData?: IAccel[] | null;
  
  // Player configuration
  autoPlay?: boolean;
  showControls?: boolean;
  showMap?: boolean;
  speedUnit?: 'km/h' | 'mph';
  
  // Event callbacks
  onTimeUpdate?: (currentTime: number) => void;
  onDurationChange?: (duration: number) => void;
  onPlay?: () => void;
  onPause?: () => void;
  onError?: (error: string) => void;
  
  // Styling
  className?: string;
}
```

**Example:**

```tsx
<VideoPlayer
  videoUrl="https://example.com/video.mp4"
  enableMetadataParsing={true}
  autoPlay={true}
  showMap={true}
  speedUnit="km/h"
  onTimeUpdate={(time) => console.log('Current time:', time)}
  onError={(error) => console.error('Video error:', error)}
/>
```

**Key Features:**
- 🎬 Advanced video controls with frame stepping
- 🗺️ Integrated GPS map with route visualization
- 📊 Real-time G-sensor data display
- 🎨 Dark/light mode support

#### MapComponent

Displays GPS tracking data on an interactive map.

```tsx
interface MapComponentProps {
  gpsPoints?: GpsPoint[];
  currentTime?: number;
  sensorData?: IAccel[];
  speedUnit?: 'km/h' | 'mph';
  mapStyle?: 'streets' | 'satellite' | 'outdoors' | 'light' | 'dark';
  height?: string;
  className?: string;
}
```

**Example:**

```tsx
<MapComponent
  gpsPoints={gpsData}
  currentTime={30}
  speedUnit="mph"
  mapStyle="satellite"
  height="300px"
/>
```

#### EventComponent

Visualizes G-sensor acceleration data.

```tsx
interface EventComponentProps {
  sensorData?: IAccel[];
  currentTime?: number;
  videoDuration?: number;
  height?: string;
  className?: string;
}
```

**Example:**

```tsx
<EventComponent
  sensorData={accelerationData}
  currentTime={30}
  videoDuration={120}
  height="100px"
/>
```

### Utilities

#### GPS Data Parsing

```tsx
import { parseGpsData, GpsParsingStatus } from 'fleeta-video-player';

const result = parseGpsData(base64Data);

if (result.status === GpsParsingStatus.SUCCESS) {
  console.log('GPS points:', result.points);
}
```

#### Sensor Data Parsing

```tsx
import { parseSensorData, SensorParsingStatus } from 'fleeta-video-player';

const result = parseSensorData(base64Data);

if (result.status === SensorParsingStatus.SUCCESS) {
  console.log('Sensor data:', result.points);
}
```

#### MP4 Metadata Extraction

```tsx
import { fetchAndParseMP4 } from 'fleeta-video-player';

const metadata = await fetchAndParseMP4('https://example.com/video.mp4');

console.log('GPS data:', metadata.gps);
console.log('Sensor data:', metadata.sensor);
console.log('Thumbnail:', metadata.thumbnail);
```

## 🎨 Styling

FleetA VideoPlayer uses Tailwind CSS classes. You can:

1. **Use default styles** - Include the CSS bundle
2. **Custom styling** - Override with your own CSS
3. **Tailwind integration** - Use Tailwind classes directly

```tsx
// Include component styles
import 'fleeta-components/dist/style.css';

// Custom styling
<VideoPlayer 
  className="my-custom-player border-2 border-blue-500"
  videoUrl={url}
/>
```

## 🌳 Tree Shaking

Import only what you need to reduce bundle size:

```tsx
// Import VideoPlayer (includes all sub-components)
import { VideoPlayer } from 'fleeta-components';

// Import only utilities
import { parseGpsData } from 'fleeta-components';

// Import only types (zero runtime cost)
import type { VideoPlayerProps } from 'fleeta-components';
```

**Bundle size savings:**
- VideoPlayer only: ~40% smaller
- GPS parsing only: ~80% smaller  
- Utilities only: ~90% smaller
- Types only: 100% smaller (no runtime cost)

## 🔧 Configuration

### Environment Variables

Set up Mapbox for map functionality:

```bash
VITE_MAPBOX_ACCESS_TOKEN=your_token_here
```

### TypeScript

FleetA Video Player includes complete TypeScript definitions:

```tsx
import type { 
  VideoPlayerProps,
  GpsPoint,
  IAccel,
  ExtractedMetadata 
} from 'fleeta-components';
```

## 📱 Responsive Design

The components are fully responsive and work on all screen sizes:

```tsx
<div className="w-full h-screen md:h-96">
  <VideoPlayer
    videoUrl={url}
    showMap={true}
    className="w-full h-full"
  />
</div>
```

## 🚗 Key Features

### GPS Tracking
- Real-time vehicle position
- Route visualization
- Speed display (km/h or mph)
- Heading direction

### G-Sensor Visualization
- Acceleration visualization
- Event detection
- Synchronized with video playback

### MP4 Metadata
- Automatic data extraction
- GPS and sensor parsing
- Thumbnail generation

## 🔍 Advanced Examples

### Custom GPS Data

```tsx
const customGpsPoints: GpsPoint[] = [
  {
    timestamp: 0,
    lat: 37.7749,
    lng: -122.4194,
    relativeTime: 0,
    speedKmh: 50,
    speedKnots: 27,
    course: 90
  }
];

<VideoPlayer
  videoUrl={url}
  gpsPoints={customGpsPoints}
  showMap={true}
/>
```

### Event Handling

```tsx
<VideoPlayer 
  videoUrl={url}
  onTimeUpdate={(time) => {
    console.log(`Video time: ${time}s`);
  }}
  onPlay={() => {
    console.log('Video started playing');
  }}
  onError={(error) => {
    console.error('Playback error:', error);
  }}
/>
```

### Dark Mode

```tsx
// Manual dark mode
<div className="dark">
  <VideoPlayer 
    videoUrl={url}
    mapStyle="dark"
  />
</div>
```

## 🛠️ Development

### Building from Source

```bash
git clone https://github.com/fleeta-team/fleeta-components.git
cd fleeta-components
npm install
npm run build:lib
```

### Running Tests

```bash
npm run quality:full
npm run validate:full
```

## 📄 Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📝 License

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

## 🆘 Support

- 📖 [API Documentation](./docs/API.md)
- 🐛 [Issue Tracker](https://github.com/fleeta-team/fleeta-components/issues)
- 💬 [Discussions](https://github.com/fleeta-team/fleeta-components/discussions)

---
**🎬 FleetA VideoPlayer - Complete Video Playback Solution for Fleet Management**