npm package: @percy.ai/roi-embed
Description: ROI Dashboard component for embedding in PHP applications
Latest version: 1.0.5

# ROI Dashboard Embed

A JavaScript component that allows you to embed the ROI Dashboard into any web application, including PHP applications.

## Features

- ✅ Easy integration with any web application
- ✅ Works with PHP, HTML, or any web framework
- ✅ Complete ROI dashboard functionality
- ✅ Responsive design with Tailwind CSS
- ✅ TypeScript support
- ✅ UMD and ES module builds
- ✅ Built with Vite for optimal performance

## Installation

### Option 1: NPM Package (Recommended)

```bash
npm install @percy.ai/roi-embed
```

### Option 2: Direct Script Include

Download the built files from the `dist/` directory and include them in your project.

## Quick Start

### HTML Usage

```html
<!DOCTYPE html>
<html>
<head>
    <title>ROI Dashboard</title>
    <!-- Load CSS styles -->
    <link rel="stylesheet" href="./dist/roi-embed.css">
</head>
<body>
    <div id="roi-dashboard"></div>

    <!-- Load React from CDN -->
    <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
    
    <!-- Load ROI Embed -->
    <script src="./dist/roi-embed.umd.js"></script>
    
    <script>
        window.ROIEmbed.init('roi-dashboard', {
            userId: 123,
            clientKey: 'your-client-key',
            defaultRange: {
                from: new Date(2024, 0, 1),
                to: new Date()
            }
        });
    </script>
</body>
</html>
```

### PHP Integration

```php
<?php
$userId = 123; // From your authentication system
$clientKey = 'your-client-key';
?>
<!DOCTYPE html>
<html>
<head>
    <title>ROI Dashboard</title>
    <!-- Load CSS styles -->
    <link rel="stylesheet" href="./dist/roi-embed.css">
</head>
<body>
    <div id="roi-dashboard"></div>
    
    <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
    <script src="./dist/roi-embed.umd.js"></script>
    
    <script>
        window.ROIEmbed.init('roi-dashboard', {
            userId: <?php echo json_encode($userId); ?>,
            clientKey: <?php echo json_encode($clientKey); ?>,
            defaultRange: {
                from: new Date('<?php echo date('Y-01-01'); ?>'),
                to: new Date('<?php echo date('Y-m-d'); ?>')
            }
        });
    </script>
</body>
</html>
```

### JavaScript/TypeScript

```javascript
import { initROIEmbed } from '@percy.ai/roi-embed';
import '@percy.ai/roi-embed/dist/roi-embed.css'; // Import CSS

// Initialize the dashboard
initROIEmbed('roi-dashboard', {
    userId: 123,
    clientKey: 'your-client-key',
    defaultRange: {
        from: new Date(2024, 0, 1),
        to: new Date()
    }
}).then(root => {
    console.log('ROI Dashboard initialized successfully');
}).catch(error => {
    console.error('Failed to initialize ROI Dashboard:', error);
});
```

## Required Files

When using the embed, you need to include **both** files:

1. **JavaScript**: `roi-embed.umd.js` (1.72MB) - The component logic
2. **CSS**: `roi-embed.css` (66KB) - Tailwind CSS and component styles

## Configuration Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `userId` | number | Yes | The ID of the user to display ROI data for |
| `clientKey` | string | No | Client API key for authentication |
| `defaultRange` | object | No | Default date range for the dashboard |
| `defaultRange.from` | Date | No | Start date for the default range |
| `defaultRange.to` | Date | No | End date for the default range |
| `apiUrl` | string | No | Custom API URL (uses default if not provided) |

## Examples

Complete examples are provided in the package:

- `example.html` - Basic HTML integration
- `example.php` - PHP application integration

## Build Information

The package includes:

- **UMD Build** (`roi-embed.umd.js`): For direct browser usage with `<script>` tags
- **ES Module Build** (`roi-embed.es.js`): For modern bundlers and ES6 imports
- **CSS Styles** (`roi-embed.css`): Tailwind CSS and component styles
- **TypeScript Declarations** (`*.d.ts`): Full TypeScript support

### Bundle Sizes

- UMD: 1.72MB (482KB gzipped)
- ES Module: 2.38MB (558KB gzipped)
- CSS: 66KB (12KB gzipped)

## Browser Support

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

## Development

To build from source:

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Watch for changes during development
pnpm dev
```

## Troubleshooting

### Common Issues

1. **Unstyled components**
   - Make sure you're loading the CSS file: `<link rel="stylesheet" href="./dist/roi-embed.css">`
   - CSS must be loaded before the JavaScript

2. **"ROI Embed library not loaded" error**
   - Ensure the script is loaded before trying to initialize
   - Check that the path to `roi-embed.umd.js` is correct

3. **React dependencies missing**
   - Make sure React and ReactDOM are loaded before the ROI embed script
   - Use the CDN links provided in the examples

4. **Container not found error**
   - Ensure the target div element exists before calling `init()`
   - Use `DOMContentLoaded` event to ensure DOM is ready

### Debug Mode

Add this to enable debug logging:

```javascript
window.ROI_DEBUG = true;
```

## Support

For issues and questions, please check the package documentation or contact support.

## License

This package is part of the Percy.ai ecosystem.