npm package: @fuseloader/lite
Description: A versatile and customizable file upload and processing component for React applications. Supports CSV, Excel, and various data formats with advanced data transformation, validation, and visualization capabilities. Ideal for building robust data-driven UI
Author: Joshua Briceno Zamora
Latest version: 1.1.15

# FuseLoader

FuseLoader is a versatile and customizable file upload and processing component for React applications. It provides an easy-to-use interface for uploading and processing CSV, Excel, and other file types.

## Installation

```bash
npm install @fuseloader/lite
```

## Screenshot

![FuseLoader Screenshot](fuseloader.png)

## Configuration Parameters

The FuseLoader component accepts the following configuration parameters:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `onFileUpload` | Function | Required | Callback function called when a file is successfully uploaded and processed. Receives `(file, sheetData)` as arguments. |
| `onClose` | Function | Optional | Callback function called when the close button is clicked. |
| `headerTemplate` | Object | Optional | Template for mapping CSV headers to specific keys. |
| `formatValidation` | Function | Optional | Custom function for additional file format validation. |
| `onNotification` | Function | Optional | Custom function for handling notifications. Receives `(message, type)` as arguments. |
| `allowedTypes` | Array<string> | `['csv']` | Array of allowed file types. Options: `'csv'`, `'excel'`, `'xml'`, `'ods'`, `'any'`. |
| `maxSize` | number | `10 * 1024 * 1024` | Maximum allowed file size in bytes (default is 10MB). |
| `theme` | string | `'light'` | Theme of the component. Options: `'light'`, `'dark'`. |
| `animations` | Object | See below | Configuration for animations. |
| `labels` | Object | See below | Custom labels for various elements. |
| `brandColors` | Object | See below | Custom brand colors. |
| `notificationOptions` | Object | See below | Options for notifications. |
| `showCloseIcon` | boolean | `true` | Whether to show the close icon. |
| `useCardStyle` | boolean | `true` | Whether to use card styling. |
| `template` | Object | Optional | Configuration for template download. |
| `customCSS` | Object | Optional | Custom CSS styles for buttons and labels. |
| `returnNotificationString` | boolean | `false` | Whether to return notification as a string instead of displaying it. |
| `analytics` | Object | Optional | Configuration for analytics integration. |

### Animations Object

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `dropZone` | boolean | `true` | Enable/disable drop zone animations. |
| `processProgress` | boolean | `true` | Enable/disable process progress animations. |
| `filePreview` | boolean | `true` | Enable/disable file preview animations. |

### Labels Object

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `title` | string | `'File Processor'` | Title of the component. |
| `dropZoneText` | string | `'Drag and drop your file here'` | Text displayed in the drop zone. |
| `browseText` | string | `'browse'` | Text for the browse file action. |
| `maxSizeText` | string | `'Maximum file size: {size}'` | Text for maximum file size information. |
| `processingText` | string | `'Processing your file...'` | Text displayed during file processing. |
| `processButtonText` | string | `'Process File'` | Text for the process button. |
| `downloadTemplateText` | string | `'Download Template'` | Text for the download template action. |

### Brand Colors Object

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `primary` | string | `'#3498db'` | Primary brand color. |
| `secondary` | string | `'#2ecc71'` | Secondary brand color. |
| `accent` | string | `'#e74c3c'` | Accent brand color. |

### Notification Options Object

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `position` | string | `'bottom-right'` | Position of the notification. Options: `'top-right'`, `'top-left'`, `'bottom-right'`, `'bottom-left'`. |
| `duration` | number | `2000` | Duration of the notification in milliseconds. |

### Template Object

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `enabled` | boolean | false |
| `url` | string | `''` | URL of the template file. |
| `filename` | string | `'template.csv'` | Filename for the downloaded template. |

### Analytics Object

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable/disable analytics tracking. |
| `trackingId` | string | `''` | Google Analytics tracking ID. |


1. When using the FuseLoader component, users can enable Google Analytics by passing the configuration:

```typescript
import { FuseLoader } from '@fuseloader/lite';

const App = () => {
  return (
    <FuseLoader
      onFileUpload={handleFileUpload}
      allowedTypes={['csv', 'excel']}
      maxSize={5 * 1024 * 1024}
      googleAnalytics={{
        enabled: true,
        trackingId: 'G-XXXXXXXXXX' // Replace with actual Google Analytics 4 Measurement ID
      }}
    />
  );
};
```

2. With this configuration, the FuseLoader component will automatically track the following events:

1. File Upload (Success and Error)
2. File Processing (Success and Error)



3. These events will appear in the Google Analytics 4 dashboard under the "Events" section.
4. Users can create custom reports and analyze the data to gain insights into how their file upload component is being used.


Remember to remind users to replace 'G-XXXXXXXXXX' with their actual Google Analytics 4 Measurement ID.

## Advanced Usage

More complex examples and use cases will be documented here.
Here a sample of implementation 

```typescript
import React from 'react';
import { FuseLoader, SheetRow, FuseLoaderConfig } from '@fuseloader/lite';

function App() {
  const handleFileUpload = (file: File, sheetData: SheetRow[]) => {
    console.log('File uploaded:', file);
    console.log('Sheet data:', sheetData);
  };

  const handleNotification = (message: string, type: 'success' | 'error' | 'warning' | 'info') => {
    console.log(`Custom notification - ${type}: ${message}`);
  };

  const handleClose = () => {
    console.log('FuseLoader closed');
    // Implement your desired close behavior here
  };

  const customConfig: FuseLoaderConfig = {
    allowedTypes: ['csv', 'excel'],
    maxSize: 5 * 1024 * 1024, // 5MB
    theme: 'dark',
    animations: {
      dropZone: true,
      processProgress: true,
      filePreview: true,
    },
    labels: {
      title: "Custom File Upload",
      dropZoneText: "Drop your file here",
      browseText: "choose file",
      maxSizeText: "Max size: {size}",
      processingText: "Processing your file...",
      processButtonText: "Upload File",
      downloadTemplateText: "Download Template"
    },
    brandColors: {
      primary: '#9b59b6',
      secondary: '#f1c40f',
      accent: '#1abc9c',
    },
    notificationOptions: {
      position: 'top-right',
      duration: 100,
    },
    showCloseIcon: true,
    useCardStyle: true,
    template: {
      enabled: true,
      url: 'https://example.com/template.csv',
      filename: 'custom_template.csv'
    },
    customCSS: {
      button: {
        fontFamily: 'Arial, sans-serif',
        fontSize: '14px',
        letterSpacing: '0.5px',
      },
      labels: {
        fontSize: '14px',
        fontFamily: 'Roboto, sans-serif',
        lineHeight: '1.5',
      },
    },
    returnNotificationString: true,
  };

  return (
    <div className="min-h-screen p-4 space-y-8">
      <div className="flex flex-col items-center gap-8 max-w-3xl mx-auto">
        <FuseLoader
          onFileUpload={handleFileUpload}
          showCloseIcon={false}
          useCardStyle={false}
          allowedTypes={['csv']}
          maxSize={1 * 1024 * 1024} // 1MB
        />

        <FuseLoader
          onFileUpload={handleFileUpload}
          {...customConfig}
          onNotification={handleNotification}
          onClose={handleClose}
          formatValidation={(file: File) => {
            // Custom format validation logic
            return new Promise((resolve, reject) => {
              if (file.size > 1024 * 1024) { // 1MB
                reject(new Error('File size must be less than 1MB'));
              } else {
                resolve(true);
              }
            });
          }}
        />
      </div>
    </div>
  );
}

export default App;
```