solvice-vrp-components/README.md

React components library for visualizing VRP problems in Mintlify documentation

# Solvice VRP Components

A React component library for visualizing Vehicle Routing Problem (VRP) data in Mintlify documentation sites. Built with shadcn/ui styling and distributed via CDN for easy integration.

## Features

- 🚀 **CDN Ready**: Direct integration via unpkg/jsdelivr
- 🎨 **shadcn/ui Styling**: Beautiful, consistent design system
- 🔄 **Auto-refresh**: Real-time data updates every 60 seconds
- 📱 **Responsive**: Works across all screen sizes
- ♿ **Accessible**: Full keyboard navigation and screen reader support
- 🎯 **TypeScript**: Complete type safety
- 🧪 **Mock API**: Development-ready with realistic test data

## Quick Start

### CDN Usage (Recommended)

```html
<!-- Load React (peer dependency) -->
<script src="https://unpkg.com/react@18.2.0/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18.2.0/umd/react-dom.production.min.js"></script>

<!-- Load VRP Components -->
<script src="https://unpkg.com/solvice-vrp-components@1.0.0/dist/solvice-vrp-components.umd.js"></script>

<script>
  // Configure API key
  window.SOLVICE_API_KEY = 'your-api-key-here';
  
  // Use the component
  const { createElement: h } = React;
  const { SolveJobsTable } = window.SolviceVRP;
  
  ReactDOM.render(
    h(SolveJobsTable, { 
      size: 'medium',
      pageSize: 10
    }),
    document.getElementById('vrp-table')
  );
</script>
```

### NPM Installation

```bash
npm install solvice-vrp-components react react-dom
```

```jsx
import { SolveJobsTable } from 'solvice-vrp-components';

function App() {
  return (
    <SolveJobsTable
      size="medium"
      pageSize={10}
      apiKey="your-api-key"
    />
  );
}
```

## Components

### SolveJobsTable

Displays a paginated table of VRP solve jobs with auto-refresh functionality.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Table size variant |
| `pageSize` | `number` | `10` | Number of jobs per page |
| `apiKey` | `string` | `undefined` | Solvice API key (optional if set globally) |
| `refreshInterval` | `number` | `60000` | Auto-refresh interval in milliseconds |
| `className` | `string` | `undefined` | Additional CSS classes |

#### Example

```jsx
<SolveJobsTable
  size="large"
  pageSize={20}
  refreshInterval={30000}
  className="my-custom-class"
/>
```

## Configuration

### Environment Variables

Set your API key using one of these methods:

**Global Window Variable:**
```javascript
window.SOLVICE_API_KEY = 'your-api-key-here';
```

**Environment Variable (NPM usage):**
```bash
SOLVICE_API_KEY=your-api-key-here
```

**Component Prop:**
```jsx
<SolveJobsTable apiKey="your-api-key-here" />
```

### CORS Configuration

For browser-based usage, you may need to configure CORS on your server or use a proxy:

```javascript
// Example proxy configuration
const proxyUrl = 'https://your-proxy.com/api/solvice';

// Override the API endpoint
window.SOLVICE_API_BASE_URL = proxyUrl;
```

## Mintlify Integration

### Step 1: Add to Custom Scripts

In your `mintlify.json`, add the CDN scripts:

```json
{
  "scripts": [
    {
      "src": "https://unpkg.com/react@18.2.0/umd/react.production.min.js"
    },
    {
      "src": "https://unpkg.com/react-dom@18.2.0/umd/react-dom.production.min.js"
    },
    {
      "src": "https://unpkg.com/solvice-vrp-components@1.0.0/dist/solvice-vrp-components.umd.js"
    }
  ]
}
```

### Step 2: Configure API Key

Create a component file in your `/snippets` folder:

```jsx
// /snippets/vrp-setup.jsx
export function VRPSetup() {
  if (typeof window !== 'undefined') {
    window.SOLVICE_API_KEY = 'your-api-key-here';
  }
  return null;
}
```

### Step 3: Use in MDX Files

```mdx
# VRP Dashboard

<VRPSetup />

Here are your recent VRP solve jobs:

<SolveJobsTable size="medium" pageSize={10} />

For a more compact view:

<SolveJobsTable size="small" pageSize={5} />
```

## Development

### Mock API

For development and testing, enable the mock API:

```javascript
window.USE_MOCK_API = true;
window.SOLVICE_API_KEY = 'demo-key';
```

The mock API provides:
- 45 realistic job entries
- Various job statuses (SOLVED, SOLVING, QUEUED, ERROR)
- Pagination support
- Random response delays
- Error simulation (5% chance)

### Local Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Start Storybook
npm run storybook

# Run tests
npm test

# Build for production
npm run build
```

## Bundle Information

- **UMD Bundle**: 82.93 kB (29.23 kB gzipped)
- **ES Module**: 222.88 kB (47.57 kB gzipped)
- **Global Namespace**: `window.SolviceVRP`
- **Source Maps**: Included for debugging

## Browser Support

- Chrome 80+
- Firefox 78+
- Safari 14+
- Edge 80+

## API Reference

### Job Object

```typescript
interface VRPJob {
  id: string;
  status: 'QUEUED' | 'SOLVING' | 'SOLVED' | 'ERROR' | null;
  solveDuration?: number | null;
  errors?: Array<{
    code: string;
    message: string;
  }> | null;
  warnings?: Array<{
    code: string;
    message: string;
  }> | null;
}
```

### API Response

```typescript
interface VRPJobsResponse {
  jobs: VRPJob[];
  total: number;
  page: number;
  pageSize: number;
}
```

## Contributing

1. Clone the repository
2. Install dependencies: `npm install`
3. Make your changes
4. Run tests: `npm test`
5. Submit a pull request

## License

MIT © Christophe Van Huele

## Links

- [GitHub Repository](https://github.com/cvhue/vrp-components)
- [npm Package](https://www.npmjs.com/package/solvice-vrp-components)
- [Storybook Documentation](https://github.com/cvhue/vrp-components/tree/main/stories)
- [Issue Tracker](https://github.com/cvhue/vrp-components/issues)