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)

<!-- Load React (peer dependency) -->
<script src="https://unpkg.com/[email protected]/umd/react.production.min.js"></script>
<script src="https://unpkg.com/[email protected]/umd/react-dom.production.min.js"></script>

<!-- Load VRP Components -->
<script src="https://unpkg.com/[email protected]/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

npm install solvice-vrp-components react react-dom

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

<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:

window.SOLVICE_API_KEY = 'your-api-key-here';

Environment Variable (NPM usage):

SOLVICE_API_KEY=your-api-key-here

Component Prop:

<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:

// 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:

{
  "scripts": [
    {
      "src": "https://unpkg.com/[email protected]/umd/react.production.min.js"
    },
    {
      "src": "https://unpkg.com/[email protected]/umd/react-dom.production.min.js"
    },
    {
      "src": "https://unpkg.com/[email protected]/dist/solvice-vrp-components.umd.js"
    }
  ]
}

Step 2: Configure API Key

Create a component file in your /snippets folder:

// /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

# 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:

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

# 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

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

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
• npm Package
• Storybook Documentation
• Issue Tracker