Vanilla Package API

The @route-optimization/vanilla package provides a framework-agnostic JavaScript API for route visualization.

Installation

npm install @route-optimization/vanilla

No framework dependencies required - works with plain JavaScript, TypeScript, or any framework.

Classes

RouteMap

Main class for managing map instances and routes.

Constructor

const routeMap = new RouteMap(config: RouteMapConfig);

RouteMapConfig:

interface RouteMapConfig extends MapConfig {
  container: string | HTMLElement;
  onMapReady?: () => void;
  onError?: (error: Error) => void;
}

Property	Type	Required	Description
apiKey	string	Yes	Google Maps API key
container	string | HTMLElement	Yes	Map container element or ID
center	LatLng	No	Initial map center
zoom	number	No	Initial zoom level
onMapReady	() => void	No	Callback when map is ready
onError	(error: Error) => void	No	Error callback

Methods

initialize()

Initialize the map instance.

await routeMap.initialize(): Promise<void>

Example:

const routeMap = new RouteMap({
  apiKey: 'YOUR_API_KEY',
  container: 'map',
  center: { lat: 13.7563, lng: 100.5018 },
  zoom: 12,
});

await routeMap.initialize();

renderRoute()

Render a route on the map.

routeMap.renderRoute(route: Route, options?: RouteRenderOptions): void

Example:

routeMap.renderRoute(route, {
  color: '#FF5722',
  polyline: {
    strokeWeight: 5,
    strokeOpacity: 0.8,
  },
});

clearRoutes()

Clear all routes from the map.

routeMap.clearRoutes(): void

addMarker()

Add a marker for a stop.

routeMap.addMarker(stop: Stop, config?: MarkerConfig): void

Example:

routeMap.addMarker(
  {
    id: 'stop-1',
    location: { lat: 13.7563, lng: 100.5018 },
    type: 'DELIVERY',
    sequence: 0,
  },
  {
    label: 'A',
    color: '#4CAF50',
  }
);

removeMarker()

Remove a specific marker.

routeMap.removeMarker(stopId: string): void

clearMarkers()

Remove all markers.

routeMap.clearMarkers(): void

fitBounds()

Fit map to show all markers/routes.

routeMap.fitBounds(bounds?: MapBounds): void

setCenter()

Set map center.

routeMap.setCenter(center: LatLng): void

setZoom()

Set zoom level.

routeMap.setZoom(zoom: number): void

getCenter()

Get current map center.

routeMap.getCenter(): LatLng | null

getZoom()

Get current zoom level.

routeMap.getZoom(): number | null

getBounds()

Get current map bounds.

routeMap.getBounds(): MapBounds | null

getCurrentRoute()

Get the currently displayed route.

routeMap.getCurrentRoute(): Route | null

isReady()

Check if map is initialized.

routeMap.isReady(): boolean

destroy()

Destroy the map and clean up resources.

routeMap.destroy(): void

MapRenderer

Utility class for rendering customization and statistics.

Constructor

const renderer = new MapRenderer(config?: MapRendererConfig);

MapRendererConfig:

interface MapRendererConfig {
  color?: string;
  strokeWeight?: number;
  strokeOpacity?: number;
  markerSize?: 'small' | 'medium' | 'large';
  showSequence?: boolean;
  animateMarkers?: boolean;
}

Property	Type	Default	Description
color	string	'#4285F4'	Default route color
strokeWeight	number	4	Polyline stroke weight
strokeOpacity	number	0.8	Polyline opacity
markerSize	string	'medium'	Marker size
showSequence	boolean	true	Show sequence numbers
animateMarkers	boolean	false	Animate marker placement

Methods

generateMarkerConfig()

Generate marker configuration for a stop.

renderer.generateMarkerConfig(stop: Stop, index: number): MarkerConfig

Example:

const config = renderer.generateMarkerConfig(stop, 0);
// Returns: { label: '1', color: '#4285F4' }

generatePolylineOptions()

Generate polyline rendering options.

renderer.generatePolylineOptions(): RouteRenderOptions['polyline']

generateRenderOptions()

Generate complete rendering options.

renderer.generateRenderOptions(): RouteRenderOptions

calculateRouteStats()

Calculate route statistics.

renderer.calculateRouteStats(route: Route): {
  totalDistance: number;
  totalDuration: number;
  stopCount: number;
  segmentCount: number;
}

Example:

const stats = renderer.calculateRouteStats(route);
console.log(`Distance: ${stats.totalDistance}m`);
console.log(`Duration: ${stats.totalDuration}s`);
console.log(`Stops: ${stats.stopCount}`);

generateRouteSummary()

Generate route summary HTML.

renderer.generateRouteSummary(route: Route): string

Example:

const html = renderer.generateRouteSummary(route);
document.getElementById('summary').innerHTML = html;

generateMarkerList()

Generate HTML list of markers.

renderer.generateMarkerList(stops: Stop[]): string

updateConfig()

Update renderer configuration.

renderer.updateConfig(config: Partial<MapRendererConfig>): void

Example:

renderer.updateConfig({
  color: '#FF0000',
  strokeWeight: 6,
});

getConfig()

Get current configuration.

renderer.getConfig(): MapRendererConfig

Examples

Basic Usage

<!DOCTYPE html>
<html>
  <head>
    <title>Route Map</title>
    <style>
      #map {
        width: 100%;
        height: 600px;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>

    <script type="module">
      import { RouteMap } from '@route-optimization/vanilla';

      const routeMap = new RouteMap({
        apiKey: 'YOUR_API_KEY',
        container: 'map',
        center: { lat: 13.7563, lng: 100.5018 },
        zoom: 12,
        onMapReady: () => console.log('Map ready!'),
        onError: (error) => console.error('Error:', error),
      });

      await routeMap.initialize();

      const route = {
        id: 'route-1',
        vehicleId: 'vehicle-1',
        stops: [
          {
            id: 'depot',
            location: { lat: 13.7563, lng: 100.5018 },
            type: 'START',
            sequence: 0,
          },
          {
            id: 'delivery-1',
            location: { lat: 13.7467, lng: 100.5342 },
            type: 'DELIVERY',
            label: 'Customer #1',
            sequence: 1,
          },
        ],
        totalDistance: 5420,
        totalDuration: 900,
      };

      routeMap.renderRoute(route);
    </script>
  </body>
</html>

With MapRenderer

import { RouteMap, MapRenderer } from '@route-optimization/vanilla';

// Create custom renderer
const renderer = new MapRenderer({
  color: '#FF5722',
  strokeWeight: 6,
  showSequence: true,
});

// Initialize map
const routeMap = new RouteMap({
  apiKey: 'YOUR_API_KEY',
  container: 'map',
});

await routeMap.initialize();

// Render with custom options
const options = renderer.generateRenderOptions();
routeMap.renderRoute(route, options);

// Display route stats
const stats = renderer.calculateRouteStats(route);
document.getElementById('stats').innerHTML = renderer.generateRouteSummary(route);

Dynamic Route Updates

let currentRoute = null;

// Add new stop
function addStop(location) {
  const newStop = {
    id: `stop-${Date.now()}`,
    location,
    type: 'DELIVERY',
    sequence: currentRoute ? currentRoute.stops.length : 0,
  };

  currentRoute = {
    ...currentRoute,
    stops: [...(currentRoute?.stops || []), newStop],
  };

  routeMap.clearRoutes();
  routeMap.renderRoute(currentRoute);
}

// Listen for map clicks
google.maps.event.addListener(map, 'click', (event) => {
  const location = {
    lat: event.latLng.lat(),
    lng: event.latLng.lng(),
  };
  addStop(location);
});

Interactive Controls

<div id="map"></div>
<div id="controls">
  <button onclick="zoomIn()">+</button>
  <button onclick="zoomOut()">-</button>
  <button onclick="clearRoute()">Clear</button>
</div>

<script type="module">
  import { RouteMap } from '@route-optimization/vanilla';

  const routeMap = new RouteMap({
    apiKey: 'YOUR_API_KEY',
    container: 'map',
  });

  await routeMap.initialize();

  window.zoomIn = () => {
    const currentZoom = routeMap.getZoom();
    if (currentZoom !== null) {
      routeMap.setZoom(currentZoom + 1);
    }
  };

  window.zoomOut = () => {
    const currentZoom = routeMap.getZoom();
    if (currentZoom !== null) {
      routeMap.setZoom(currentZoom - 1);
    }
  };

  window.clearRoute = () => {
    routeMap.clearRoutes();
  };
</script>

Error Handling

const routeMap = new RouteMap({
  apiKey: 'YOUR_API_KEY',
  container: 'map',
  onError: (error) => {
    // Display error to user
    document.getElementById('error').textContent = error.message;
    document.getElementById('error').style.display = 'block';
  },
});

try {
  await routeMap.initialize();
} catch (error) {
  console.error('Failed to initialize map:', error);
}

if (routeMap.isReady()) {
  routeMap.renderRoute(route);
}

TypeScript Support

Full TypeScript definitions included:

import { RouteMap, MapRenderer } from '@route-optimization/vanilla';
import type { Route, RouteMapConfig, MapRendererConfig } from '@route-optimization/vanilla';

const config: RouteMapConfig = {
  apiKey: 'YOUR_API_KEY',
  container: 'map',
  center: { lat: 13.7563, lng: 100.5018 },
  zoom: 12,
};

const routeMap = new RouteMap(config);

Browser Support

• Chrome/Edge: Latest 2 versions
• Firefox: Latest 2 versions
• Safari: Latest 2 versions

Next Steps

• Core Package API
• Vanilla Examples
• Vanilla Integration Guide