@quantaroute/checkout 1.1.1 → 1.2.0

package/src/components/MapPinSelector.tsx

@@ -0,0 +1,405 @@
+import React, { useEffect, useRef, useState, useCallback } from 'react';
+import maplibregl from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+import { getDigiPin, isWithinIndia } from '../core/digipin';
+import { useGeolocation } from '../hooks/useGeolocation';
+import type { MapPinSelectorProps } from '../core/types';
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** India's geographic center – shown when no default location is given */
+const INDIA_CENTER = { lat: 13.004270, lng: 77.589291 };
+const MIN_ZOOM     = 6;   // users cannot zoom out beyond a useful India-level view
+const OVERVIEW_ZOOM = 9;
+const STREET_ZOOM = 18;
+
+/**
+ * Carto Positron – free vector basemap, no API key required.
+ * Attribution: © OpenStreetMap contributors © CARTO
+ * Terms: https://carto.com/legal/
+ */
+const CARTO_STYLE_URL =
+  'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json';
+
+// ─── Pin dimensions ───────────────────────────────────────────────────────────
+// MUST match the SVG width/height exactly.
+// MapLibre reads element.offsetWidth/offsetHeight to compute `anchor:'bottom'`.
+// The pin tip lives at SVG coordinate (20, 52) = bottom-center of the element.
+const PIN_W = 40;
+const PIN_H = 52;
+
+// ─── Marker helper ───────────────────────────────────────────────────────────
+
+function computeDigiPinSafe(la: number, lo: number): string | null {
+  if (!isWithinIndia(la, lo)) return null;
+  try {
+    return getDigiPin(la, lo);
+  } catch {
+    return null;
+  }
+}
+
+function createPinElement(): HTMLDivElement {
+  const el = document.createElement('div');
+  el.className = 'qr-pin';
+  el.setAttribute('aria-label', 'Drag to adjust your location');
+
+  // ─ Set explicit inline dimensions ─────────────────────────────────────────
+  // This is critical: without them, the browser may add inline-baseline
+  // whitespace below the <svg> tag, making offsetHeight > PIN_H and causing
+  // the anchor='bottom' point to land below the actual pin tip.
+  el.style.width  = `${PIN_W}px`;
+  el.style.height = `${PIN_H}px`;
+
+  el.innerHTML = `
+    <svg
+      class="qr-pin__svg"
+      width="${PIN_W}"
+      height="${PIN_H}"
+      viewBox="0 0 ${PIN_W} ${PIN_H}"
+      overflow="visible"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+    >
+      <defs>
+        <!--
+          The filter region must be generous enough to contain the shadow blur.
+          stdDeviation=3 → ~9px blur radius; our region extends 50% on each side.
+          overflow="visible" on the <svg> lets it paint outside the viewport.
+        -->
+        <filter id="qr-pin-shadow" x="-60%" y="-40%" width="220%" height="220%">
+          <feDropShadow dx="0" dy="3" stdDeviation="3.5"
+            flood-color="#000" flood-opacity="0.28"/>
+        </filter>
+      </defs>
+
+      <!-- Teardrop body — tip is at (20, 52) = bottom-center of the SVG -->
+      <path
+        d="M20 0C9.402 0 0 9.402 0 20C0 34 20 52 20 52S40 34 40 20C40 9.402 30.598 0 20 0Z"
+        fill="#0ea5e9"
+        filter="url(#qr-pin-shadow)"
+      />
+      <!-- Dot inside the pin -->
+      <circle cx="20" cy="20" r="9" fill="white"/>
+      <circle cx="20" cy="20" r="5" fill="#0ea5e9"/>
+    </svg>
+
+    <!--
+      Pulse ring — position: absolute inside .qr-pin (position: relative).
+      bottom: -(height/2)  →  bottom: -10px  centres the 20×20 circle
+      exactly at y = PIN_H = 52px = the pin tip coordinate.
+    -->
+    <div class="qr-pin__pulse" aria-hidden="true"></div>
+  `;
+  return el;
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+const MapPinSelector: React.FC<MapPinSelectorProps> = ({
+  onLocationConfirm,
+  defaultLat,
+  defaultLng,
+  mapHeight = '380px',
+  theme: _theme = 'light',   // kept for future dark-mode pin tint; unused for now
+  indiaBoundaryUrl,
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const mapRef = useRef<maplibregl.Map | null>(null);
+  const markerRef = useRef<maplibregl.Marker | null>(null);
+
+  // Compute once here so both state init and the useEffect use the same values.
+  const initLat = defaultLat ?? INDIA_CENTER.lat;
+  const initLng = defaultLng ?? INDIA_CENTER.lng;
+  const hasDefault = defaultLat !== undefined && defaultLng !== undefined;
+
+  const [lat, setLat] = useState(initLat);
+  const [lng, setLng] = useState(initLng);
+  // Compute DigiPin eagerly (offline, ~0.1 ms) so the badge shows immediately.
+  const [digipin, setDigipin] = useState<string | null>(() =>
+    computeDigiPinSafe(initLat, initLng)
+  );
+  const [mapLoaded, setMapLoaded] = useState(false);
+
+  const { loading: geoLoading, error: geoError, locate, clearError } = useGeolocation();
+
+  // Update DigiPin badge (offline, instant)
+  const refreshDigipin = useCallback((la: number, lo: number) => {
+    setDigipin(computeDigiPinSafe(la, lo));
+  }, []);
+
+  // ── Map initialization (runs once) ────────────────────────────────────────
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    // ── Fetch India boundary GeoJSON eagerly, in parallel with map style load ──
+    // Starting the fetch here (before map fires 'load') means by the time the
+    // map is ready the data is likely already parsed → zero perceived delay.
+    // Silent failure: the boundary is a legal safeguard, not critical UI.
+    const boundaryPromise: Promise<unknown> = indiaBoundaryUrl
+      ? fetch(indiaBoundaryUrl)
+          .then((r) => (r.ok ? r.json() : null))
+          .catch(() => null)
+      : Promise.resolve(null);
+
+    const initZoom = hasDefault ? STREET_ZOOM : OVERVIEW_ZOOM;
+
+    const map = new maplibregl.Map({
+      container: containerRef.current,
+      style: CARTO_STYLE_URL,
+      center: [initLng, initLat],
+      zoom: initZoom,
+      minZoom: MIN_ZOOM,   // lock: cannot zoom out past level 7
+      attributionControl: false,
+      // Smooth touch gestures on mobile (tap center for zoom)
+      touchZoomRotate: true,
+    });
+
+    // Attribution (required by Carto & OSM terms)
+    map.addControl(
+      new maplibregl.AttributionControl({
+        compact: true,
+        customAttribution:
+          '© <a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">OpenStreetMap</a> contributors &nbsp;© <a href="https://carto.com/attributions" target="_blank" rel="noopener">CARTO</a>',
+      }),
+      'bottom-right'
+    );
+
+    // Zoom +/− (hidden on small screens via CSS)
+    map.addControl(
+      new maplibregl.NavigationControl({ showCompass: false }),
+      'top-right'
+    );
+
+    map.on('load', () => {
+      setMapLoaded(true);
+
+      // ── India boundary overlay (legal compliance) ────────────────────────
+      // Resolves instantly if the fetch finished before map loaded (typical),
+      // or waits the remaining milliseconds if still in-flight.
+      boundaryPromise.then((geoJson) => {
+        if (!geoJson || !map.isStyleLoaded()) return;
+        try {
+          map.addSource('india-boundary', {
+            type: 'geojson',
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            data: geoJson as any,
+          });
+          map.addLayer({
+            id: 'india-boundary-line',
+            type: 'line',
+            source: 'india-boundary',
+            paint: {
+              'line-color': '#94a3b8',   // slate-400 — subtle grey
+              'line-width': 1.5,
+              'line-opacity': 0.65,
+            },
+          });
+        } catch {
+          // Silent: duplicate source/layer on hot-reload is not an error
+        }
+      });
+
+      // Create draggable pin marker.
+      // anchor='bottom' → MapLibre aligns element's bottom-center with the coord.
+      // Our SVG tip is at (20, 52) = exactly the bottom-center of the 40×52 element.
+      // No offset needed — any offset shifts the tip away from the coordinate.
+      const pinEl = createPinElement();
+      const marker = new maplibregl.Marker({
+        element: pinEl,
+        draggable: true,
+        anchor: 'bottom',
+      })
+        .setLngLat([initLng, initLat])
+        .addTo(map);
+
+      // Live DigiPin update while dragging
+      marker.on('drag', () => {
+        const pos = marker.getLngLat();
+        setLat(pos.lat);
+        setLng(pos.lng);
+        refreshDigipin(pos.lat, pos.lng);
+      });
+
+      // Re-center map after drag ends
+      marker.on('dragend', () => {
+        const pos = marker.getLngLat();
+        map.easeTo({ center: [pos.lng, pos.lat], duration: 250 });
+      });
+
+      markerRef.current = marker;
+      // DigiPin is already computed in useState() init; no need to recompute here.
+    });
+
+    // Tap/click map to reposition pin
+    map.on('click', (e) => {
+      const pos = e.lngLat;
+      markerRef.current?.setLngLat([pos.lng, pos.lat]);
+      setLat(pos.lat);
+      setLng(pos.lng);
+      refreshDigipin(pos.lat, pos.lng);
+      map.easeTo({ center: [pos.lng, pos.lat], duration: 200 });
+    });
+
+    mapRef.current = map;
+
+    return () => {
+      map.remove();
+      mapRef.current = null;
+      markerRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []); // intentionally empty – runs once on mount
+
+  // ── Geolocation handler ───────────────────────────────────────────────────
+  const handleLocateMe = useCallback(() => {
+    clearError();
+    locate((userLat, userLng) => {
+      setLat(userLat);
+      setLng(userLng);
+      refreshDigipin(userLat, userLng);
+
+      if (mapRef.current) {
+        mapRef.current.flyTo({
+          center: [userLng, userLat],
+          zoom: STREET_ZOOM,
+          duration: 1400,
+          essential: true,
+        });
+      }
+      markerRef.current?.setLngLat([userLng, userLat]);
+    });
+  }, [locate, clearError, refreshDigipin]);
+
+  // ── Confirm handler ───────────────────────────────────────────────────────
+  const handleConfirm = useCallback(() => {
+    if (digipin) {
+      onLocationConfirm(lat, lng, digipin);
+    }
+  }, [lat, lng, digipin, onLocationConfirm]);
+
+  const isInIndia = digipin !== null;
+  const canConfirm = isInIndia && mapLoaded;
+
+  return (
+    <div className="qr-map-wrapper">
+      {/* ── Step header ── */}
+      <div className="qr-step-header">
+        <div className="qr-step-badge">1</div>
+        <div className="qr-step-text">
+          <span className="qr-step-title">Pin Your Location</span>
+          <span className="qr-step-sub">
+            Tap the map or drag the pin to your exact home / office
+          </span>
+        </div>
+      </div>
+
+      {/* ── Map area ── */}
+      <div className="qr-map-outer" style={{ height: mapHeight }}>
+        {/* MapLibre GL container */}
+        <div ref={containerRef} className="qr-map-canvas" />
+
+        {/* DigiPin overlay badge – shown once inside India */}
+        {digipin && (
+          <div className="qr-digipin-badge" aria-live="polite" aria-label={`DigiPin: ${digipin}`}>
+            <span className="qr-digipin-badge__label">DigiPin</span>
+            <span className="qr-digipin-badge__code">{digipin}</span>
+          </div>
+        )}
+
+        {/* Out-of-India notice */}
+        {!isInIndia && mapLoaded && (
+          <div className="qr-map-notice" role="status">
+            Move map to India to get a DigiPin
+          </div>
+        )}
+
+        {/* Locate-me button */}
+        <button
+          className={`qr-locate-btn${geoLoading ? ' qr-locate-btn--loading' : ''}`}
+          onClick={handleLocateMe}
+          disabled={geoLoading}
+          title="Use my current location"
+          aria-label="Use my current location"
+          type="button"
+        >
+          {geoLoading ? (
+            <span className="qr-spinner" aria-hidden="true" />
+          ) : (
+          <svg
+            aria-hidden="true"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2" 
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            {/* 1. Inner solid dot */}
+            <circle cx="12" cy="12" r="3" fill="currentColor" stroke="none" />
+            
+            {/* 2. Outer ring */}
+            <circle cx="12" cy="12" r="7" />
+            
+            {/* 3. Crosshair bumps attached to the ring */}
+            <path d="M12 2v3M12 19v3M2 12h3M19 12h3" />
+          </svg>
+          )}
+        </button>
+
+        {/* Geo error toast */}
+        {geoError && (
+          <div className="qr-geo-error" role="alert">
+            <span>{geoError}</span>
+            <button
+              type="button"
+              className="qr-geo-error__dismiss"
+              onClick={clearError}
+              aria-label="Dismiss error"
+            >
+              ×
+            </button>
+          </div>
+        )}
+      </div>
+
+      {/* ── Coordinates strip ── */}
+      {mapLoaded && (
+        <div className="qr-coords-strip" aria-label="Current pin coordinates">
+          <span>{lat.toFixed(5)}° N</span>
+          <span className="qr-coords-sep">·</span>
+          <span>{lng.toFixed(5)}° E</span>
+        </div>
+      )}
+
+      {/* ── Confirm action bar ── */}
+      <div className="qr-map-actions">
+        <button
+          type="button"
+          className="qr-btn qr-btn--primary qr-btn--full"
+          onClick={handleConfirm}
+          disabled={!canConfirm}
+        >
+          Confirm Location
+          <svg
+            aria-hidden="true"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2.5"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <path d="M5 12h14M12 5l7 7-7 7" />
+          </svg>
+        </button>
+        {!isInIndia && mapLoaded && (
+          <p className="qr-map-hint">Move the pin to a location in India to continue</p>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default MapPinSelector;

package/src/core/api.ts

@@ -0,0 +1,150 @@
+import type { LocationLookupResponse } from './types';
+
+const DEFAULT_BASE_URL = 'https://api.quantaroute.com';
+
+/**
+ * Address components from Nominatim/OpenStreetMap (via reverse geocoding).
+ */
+export interface AddressComponents {
+  house_number?: string;
+  road?: string;
+  neighbourhood?: string;
+  suburb?: string;
+  city?: string;
+  state?: string;
+  postcode?: string;
+  country?: string;
+  country_code?: string;
+  name?: string; // Building/Society/POI name
+  addr_housename?: string;
+  addr_place?: string;
+  building?: string;
+  building_name?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Response from /v1/digipin/reverse endpoint.
+ */
+export interface ReverseGeocodeResponse {
+  success: boolean;
+  data: {
+    digipin: string;
+    address: string;
+    coordinates: { latitude: number; longitude: number };
+    confidence: number;
+    displayName: string;
+    addressComponents: AddressComponents;
+  };
+  error?: string;
+  message?: string;
+}
+
+/**
+ * Call QuantaRoute's Location Lookup API.
+ * Converts lat/lng → full Indian administrative address + DigiPin.
+ */
+export async function lookupLocation(
+  lat: number,
+  lng: number,
+  apiKey: string,
+  baseUrl: string = DEFAULT_BASE_URL
+): Promise<LocationLookupResponse> {
+  const url = `${baseUrl.replace(/\/$/, '')}/v1/location/lookup`;
+
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+      },
+      body: JSON.stringify({ latitude: lat, longitude: lng }),
+      signal: AbortSignal.timeout(15_000), // 15s timeout
+    });
+  } catch (err) {
+    if (err instanceof Error && err.name === 'TimeoutError') {
+      throw new Error('Request timed out. Check your internet connection.');
+    }
+    throw new Error(`Network error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (!res.ok) {
+    let body = '';
+    try {
+      body = await res.text();
+    } catch {
+      // ignore
+    }
+    if (res.status === 401 || res.status === 403) {
+      throw new Error('Invalid API key. Check your QuantaRoute API key.');
+    }
+    if (res.status === 429) {
+      throw new Error('Rate limit exceeded. Upgrade your plan or try again later.');
+    }
+    throw new Error(`API error ${res.status}: ${body || res.statusText}`);
+  }
+
+  const data = (await res.json()) as LocationLookupResponse;
+
+  if (!data.success) {
+    throw new Error(data.message ?? 'Location lookup failed');
+  }
+
+  return data;
+}
+
+/**
+ * Call QuantaRoute's Reverse Geocoding API.
+ * Converts DigiPin → address components from Nominatim/OpenStreetMap.
+ */
+export async function reverseGeocode(
+  digipin: string,
+  apiKey: string,
+  baseUrl: string = DEFAULT_BASE_URL
+): Promise<ReverseGeocodeResponse> {
+  const url = `${baseUrl.replace(/\/$/, '')}/v1/digipin/reverse`;
+
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+      },
+      body: JSON.stringify({ digipin }),
+      signal: AbortSignal.timeout(15_000), // 15s timeout
+    });
+  } catch (err) {
+    if (err instanceof Error && err.name === 'TimeoutError') {
+      throw new Error('Request timed out. Check your internet connection.');
+    }
+    throw new Error(`Network error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (!res.ok) {
+    let body = '';
+    try {
+      body = await res.text();
+    } catch {
+      // ignore
+    }
+    if (res.status === 401 || res.status === 403) {
+      throw new Error('Invalid API key. Check your QuantaRoute API key.');
+    }
+    if (res.status === 429) {
+      throw new Error('Rate limit exceeded. Upgrade your plan or try again later.');
+    }
+    throw new Error(`API error ${res.status}: ${body || res.statusText}`);
+  }
+
+  const data = (await res.json()) as ReverseGeocodeResponse;
+
+  if (!data.success) {
+    throw new Error(data.message ?? 'Reverse geocoding failed');
+  }
+
+  return data;
+}