mondial-relay-widget

🌍 Mondial Relay Widget - TypeScript/JavaScript Library

A lightweight, fully typed TypeScript/JavaScript wrapper for the Mondial Relay parcel shop picker widget (v4.1). Works with any framework: React, Vue, Angular, Svelte, etc.

✨ Features

• 🎯 Framework agnostic - Works with React, Vue, Angular, Svelte, or vanilla JS
• 📦 Automatic dependency loading - Loads jQuery, Leaflet, and the MR widget automatically
• 🎨 Full TypeScript support - Fully typed, zero any types
• 🗺️ Multiple map engines - Leaflet (default) or Google Maps
• 🌐 Multi-language support - English, Italian, Spanish, German, and French
• ⚡ Lightweight - Only ~6KB minified
• 🧹 Clean API - Simple, intuitive interface

📦 Installation

npm install mondial-relay
# or
yarn add mondial-relay

🚀 Quick Start

Basic Usage

import { MondialRelay } from 'mondial-relay';

const widget = await MondialRelay.init('#container', {
  brand: 'BDTEST  ', // Your 8-char Mondial Relay code (padded with spaces)
  onSelect: (relay) => {
    console.log('Selected:', relay.id, relay.name, relay.address);
  },
});

React Example

import { useEffect, useRef } from 'react';
import { MondialRelay, WidgetInstance } from 'mondial-relay';

export function ShipmentWidget() {
  const containerRef = useRef<HTMLDivElement>(null);
  const widgetRef = useRef<WidgetInstance | null>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    MondialRelay.init(containerRef.current, {
      brand: 'MYCODE  ',
      postCode: '75001',
      onSelect: (relay) => {
        console.log('Selected relay:', relay.name);
        // Save to your state/store
      },
      onSearchSuccess: (results) => {
        console.log('Found', results.length, 'relay points');
      },
      onNoResult: () => {
        console.log('No relay points found');
      },
    }).then((instance) => {
      widgetRef.current = instance;
    });

    return () => {
      widgetRef.current?.destroy();
    };
  }, []);

  return <div ref={containerRef} />;
}

Vue Example

<template>
  <div ref="container" />
</template>

<script setup>
import { onMounted, onUnmounted, ref } from 'vue';
import { MondialRelay } from 'mondial-relay';

const container = ref(null);
let widget = null;

onMounted(async () => {
  widget = await MondialRelay.init(container.value, {
    brand: 'MYCODE  ',
    onSelect: (relay) => {
      console.log('Relay selected:', relay.name);
    },
  });
});

onUnmounted(() => {
  widget?.destroy();
});
</script>

📋 API Reference

MondialRelay.init(container, options)

Initializes the widget in the given container.

Parameters:

• container: string | HTMLElement - CSS selector or DOM element
• options: MondialRelayOptions - Configuration object

Returns: Promise<WidgetInstance>

Options

interface MondialRelayOptions {
  // Required
  brand: string;                    // 8-char brand code (e.g. 'BDTEST  ')

  // Search filters
  country?: string;                 // ISO 2-letter code, default: 'FR'
  postCode?: string;                // Auto-search on load
  allowedCountries?: string;        // Comma-separated codes, e.g. 'FR,ES,BE'
  deliveryMode?: DeliveryMode;      // '24R' | '24L' | '24X' | 'DRI', default: '24R'
  nbResults?: number;               // Max results to show, default: 7
  weight?: number;                  // Parcel weight in grams
  searchDelay?: number;             // Days until drop-off
  searchFar?: number;               // Max search radius in km

  // Map settings
  showMap?: boolean;                // Show map, default: true
  mapInfo?: boolean;                // Show info on map select, default: true
  scrollWheel?: boolean;            // Scroll-to-zoom, default: false
  responsive?: boolean;             // Responsive layout, default: false

  // Features
  geolocation?: boolean;            // Offer browser geolocation, default: false
  customCss?: boolean;              // Disable built-in CSS, default: false
  useGoogleMaps?: boolean;          // Use Google Maps instead of Leaflet
  googleMapsKey?: string;           // Google Maps API key
  language?: string;                // ISO 639-1 language code (e.g., 'en', 'it', 'es', 'de')

  // Callbacks
  onSelect?: (relay: RelayPoint) => void;
  onSearchSuccess?: (results: RelayPoint[]) => void;
  onNoResult?: () => void;
}

WidgetInstance API

interface WidgetInstance {
  // Search for relay points by postal code
  search(postCode: string, country?: string): this;

  // Update parameters at runtime
  setParams(params: RuntimeParams): this;

  // Force map re-render (useful for modals/tabs)
  rebindMap(): this;

  // Get currently selected relay point ID
  getSelectedId(): string | null;

  // Destroy widget and clean up DOM
  destroy(): void;
}

RelayPoint

interface RelayPoint {
  id: string;           // Mondial Relay ID (e.g. '066974')
  name: string;         // Relay point name
  address: string;      // Full address
  postCode: string;     // Postal code
  city: string;         // City
  country: string;      // ISO 2-letter country code
  lat: string;          // Latitude
  lng: string;          // Longitude
  photo: string | null; // Photo URL if available
  hours: string;        // Opening hours (HTML table)
  _raw: MRRawRelay;     // Original unmodified MR data
}

💡 Examples

Chainable API

const widget = await MondialRelay.init('#picker', { brand: 'MYCODE  ' });

// Chain operations
widget
  .search('75001', 'FR')
  .setParams({ deliveryMode: '24L' })
  .rebindMap();

const selectedId = widget.getSelectedId();
console.log('Selected:', selectedId);

Dynamic Parameter Changes

widget.setParams({
  deliveryMode: '24X',        // Use friendly key
  weight: 5000,               // Update weight filter
  NbResults: '15',            // Or raw MR key
  CustomParam: 'value',       // Any raw MR parameter
});

Language Configuration

Control the widget interface language using the language option. By default, the widget displays in French.

// Display in English
const widget = await MondialRelay.init('#picker', {
  brand: 'MYCODE  ',
  language: 'en',
});

// Display in Italian
const widget = await MondialRelay.init('#picker', {
  brand: 'MYCODE  ',
  language: 'it',
});

// Display in Spanish
const widget = await MondialRelay.init('#picker', {
  brand: 'MYCODE  ',
  language: 'es',
});

// Display in German
const widget = await MondialRelay.init('#picker', {
  brand: 'MYCODE  ',
  language: 'de',
});

// Default to French (omit language parameter or use 'fr')
const widget = await MondialRelay.init('#picker', {
  brand: 'MYCODE  ',
  language: 'fr', // or simply omit this parameter
});

Note: Use ISO 639-1 language codes (e.g., 'en', 'it', 'es', 'de', 'fr'). When the language is set to 'fr' or left undefined, the widget sends an empty string to the Mondial Relay API, allowing it to determine the language automatically.

Google Maps

const widget = await MondialRelay.init('#picker', {
  brand: 'MYCODE  ',
  useGoogleMaps: true,
  googleMapsKey: 'YOUR_GOOGLE_MAPS_API_KEY',
});

Modal/Tab Handling

// After modal opens or tab becomes visible
widget.rebindMap();

🌐 Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• All modern browsers with ES2020 support

📝 Notes

• Your brand code must be exactly 8 characters. Pad with trailing spaces if needed.
• Test brand code: 'BDTEST ' (with 2 spaces)
• The widget automatically loads jQuery 2.2.4 and either Leaflet or Google Maps
• For production, consider caching these dependencies if loading multiple instances

🔗 Resources

• Mondial Relay Widget Documentation
• JSFiddle Example

🙏 Acknowledgements

Special thanks to GitHub Copilot for extensive work on the library's core architecture, TypeScript typing system, comprehensive API design, and documentation.

📄 License

MIT

🤝 Contributing

Contributions welcome! Please feel free to open issues and PRs.