@cloudparse/up-miniapps-sdk 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -788,6 +788,19 @@ interface MapProps {
     onPoiClick?: (poi: POI) => void;
     /** Route geometry to display on the map. */
     route?: GeoJSON.LineString;
+    /**
+     * Visual style for the route line the Map draws internally (both for
+     * `route` and for an active `navigation`/`navigationData` journey) —
+     * see `RouteLayerProps`. Defaults to `RouteLayer`'s own defaults
+     * (`#3b82f6` blue, solid) when omitted, so existing consumers are
+     * unaffected.
+     */
+    routeStyle?: {
+        color?: string;
+        width?: number;
+        opacity?: number;
+        dashArray?: number[];
+    };
     /** Whether to show the out-of-the-box navigation UI. */
     showNavigationUI?: boolean;
     /** Callback triggered when the user aborts/closes the navigation UI. */
@@ -814,6 +827,12 @@ interface MapProps {
          * Defaults to 'preview'.
          */
         mode?: "preview" | "navigation";
+        /**
+         * Distance in meters from the destination at which the journey
+         * counts as arrived. GPS accuracy means the live remaining distance
+         * rarely reaches exactly 0. Defaults to 15m.
+         */
+        arrivalThresholdMeters?: number;
     };
     /** Callback triggered when the navigation mode changes (e.g. from preview to navigation). */
     onNavigationModeChange?: (mode: "preview" | "navigation") => void;
@@ -832,6 +851,8 @@ interface MapProps {
         mode?: "preview" | "navigation";
         /** Function to transition to active navigation mode */
         start?: () => void;
+        /** True once the live remaining distance drops to/below `navigation.arrivalThresholdMeters`. */
+        hasArrived?: boolean;
     };
     /** Whether to show the vertical drawer and floating right controls. Defaults to true. */
     showControls?: boolean;
@@ -874,6 +895,8 @@ interface EtaData {
     onStart?: () => void;
     isCalculating?: boolean;
     error?: string | null;
+    /** True once the live remaining distance drops to/below `navigation.arrivalThresholdMeters`. */
+    hasArrived?: boolean;
 }
 
 interface MapInsets {
@@ -1030,6 +1053,12 @@ interface LiveRoutingOptions {
     enabled?: boolean;
     /** Initial mode: 'preview' or 'navigation'. Defaults to 'preview'. */
     initialMode?: "preview" | "navigation";
+    /**
+     * Distance in meters from the destination at which the journey counts
+     * as arrived (`hasArrived` becomes true). GPS accuracy means the live
+     * `currentDistanceMeters` rarely reaches exactly 0. Defaults to 15m.
+     */
+    arrivalThresholdMeters?: number;
 }
 interface LiveRoutingResult {
     /** The calculated route data from the last API call */
@@ -1048,8 +1077,15 @@ interface LiveRoutingResult {
     mode: "preview" | "navigation";
     /** Start active navigation (switch mode to 'navigation') */
     start: () => void;
+    /**
+     * True once `currentDistanceMeters` drops to/below
+     * `arrivalThresholdMeters`. Use this instead of checking
+     * `currentDistanceMeters <= 0` — the point never reaches exactly 0 with
+     * live GPS.
+     */
+    hasArrived: boolean;
 }
-declare const useLiveRouting: ({ origin: manualOrigin, destination, profile, recalculateThreshold, enabled, initialMode, }: LiveRoutingOptions) => LiveRoutingResult;
+declare const useLiveRouting: ({ origin: manualOrigin, destination, profile, recalculateThreshold, enabled, initialMode, arrivalThresholdMeters, }: LiveRoutingOptions) => LiveRoutingResult;
 /**
  * A simple hook to fetch a route once between two points.
  * Does not automatically recalculate or track user location.
@@ -1077,6 +1113,12 @@ interface DeclarativeJourneyOptions {
     origin?: [number, number] | null;
     /** Initial mode. 'preview' shows the route overview, 'navigation' starts active guidance. Defaults to 'preview'. */
     mode?: NavMode;
+    /**
+     * Distance in meters from the destination at which the journey counts
+     * as arrived (`hasArrived` becomes true). GPS accuracy means the live
+     * `distanceRemainingMeters` rarely reaches exactly 0. Defaults to 15m.
+     */
+    arrivalThresholdMeters?: number;
 }
 interface UseJourneyOptions {
     /**
@@ -1112,6 +1154,13 @@ interface UseJourneyResult {
     etaMinutes: number;
     /** Journey completion progress, 0-100. */
     progress: number;
+    /**
+     * True once the live remaining distance drops to/below
+     * `arrivalThresholdMeters`. Check this instead of
+     * `distanceRemainingMeters <= 0` — it usually never reaches exactly 0
+     * with live GPS, so a UI that waits for that may never show "arrived".
+     */
+    hasArrived: boolean;
     /** Switch from 'preview' to active 'navigation' guidance. */
     start: () => void;
     /** Cancel the journey entirely. Always returns to 'preview' the next time a journey starts. */
@@ -1153,6 +1202,14 @@ interface RouteLayerProps {
     width?: number;
     /** Opacity of the route line. Defaults to 0.8. */
     opacity?: number;
+    /**
+     * MapLibre `line-dasharray` for the colored line (the white casing
+     * underneath always stays solid, for legibility against any basemap).
+     * Units are multiples of `width`. E.g. `[0, 2]` with the layer's own
+     * `line-cap: round` (always on) renders as a dotted trail instead of a
+     * continuous line. Omit for a solid line (default).
+     */
+    dashArray?: number[];
 }
 declare const RouteLayer: React__default.FC<RouteLayerProps>;
 
@@ -1513,6 +1570,14 @@ declare class MiniAppSDK {
             destination: [number, number];
             origin?: [number, number];
             profile?: "driving" | "cycling" | "walking";
+            /**
+             * Distance in meters from the destination at which the journey
+             * counts as arrived (`useJourney().hasArrived` becomes true). GPS
+             * accuracy means the live remaining distance rarely reaches
+             * exactly 0 — this is the threshold a consumer's own UI should
+             * treat as "done" instead of waiting for that. Defaults to 15m.
+             */
+            arrivalThresholdMeters?: number;
         }) => void;
         /**
          * Starts the active navigation (active guidance).

package/dist/index.js

@@ -2010,13 +2010,15 @@ var useUserLocation = () => {
 
 // src/components/Map/hooks/useLiveRouting.ts
 import { useCallback as useCallback4, useEffect as useEffect4, useMemo as useMemo3, useRef as useRef5, useState as useState6 } from "react";
+var DEFAULT_ARRIVAL_THRESHOLD_METERS = 15;
 var useLiveRouting = ({
   origin: manualOrigin,
   destination,
   profile = "driving",
   recalculateThreshold = 50,
   enabled = true,
-  initialMode = "preview"
+  initialMode = "preview",
+  arrivalThresholdMeters = DEFAULT_ARRIVAL_THRESHOLD_METERS
 }) => {
   const [route, setRoute] = useState6(null);
   const [totalDistance, setTotalDistance] = useState6(null);
@@ -2070,6 +2072,7 @@ var useLiveRouting = ({
     }
     return dist;
   }, [trackingLocation, route, destination, getDistance]);
+  const hasArrived = currentDistanceMeters !== null && currentDistanceMeters <= arrivalThresholdMeters;
   const calculate = useCallback4(
     async (origin, dest, isNewDest) => {
       if (isRequestInProgress.current) return;
@@ -2127,6 +2130,8 @@ var useLiveRouting = ({
     if (lastResetDestKey.current !== destKey) {
       lastResetDestKey.current = destKey;
       setMode(initialMode);
+      setRoute(null);
+      setTotalDistance(null);
     }
     if (destChanged) {
       calculate(calculationOrigin, destination, true);
@@ -2152,6 +2157,7 @@ var useLiveRouting = ({
   return {
     currentDistanceMeters,
     error,
+    hasArrived,
     isCalculating,
     mode,
     recalculate: () => calculationOrigin && destination && calculate(calculationOrigin, destination, false),
@@ -2217,6 +2223,7 @@ var useJourney = (options = {}) => {
   }, []);
   const effectiveOptions = progNav || navigation;
   const internalNav = useLiveRouting({
+    arrivalThresholdMeters: effectiveOptions?.arrivalThresholdMeters,
     destination: effectiveOptions?.destination || null,
     enabled: !isAborted && !!effectiveOptions?.destination,
     initialMode: effectiveOptions?.mode || "preview",
@@ -2272,6 +2279,7 @@ var useJourney = (options = {}) => {
     distanceRemainingMeters,
     error: isActive ? internalNav.error : null,
     etaMinutes,
+    hasArrived: isActive ? internalNav.hasArrived : false,
     isActive,
     isCalculating: isActive ? internalNav.isCalculating : false,
     mode: isActive ? internalNav.mode : "preview",
@@ -2316,7 +2324,8 @@ var RouteLayer = ({
   geometry,
   color = "#3b82f6",
   width = 5,
-  opacity = 0.8
+  opacity = 0.8,
+  dashArray
 }) => {
   if (!geometry) return null;
   const data = {
@@ -2349,7 +2358,8 @@ var RouteLayer = ({
         paint: {
           "line-color": color,
           "line-opacity": opacity,
-          "line-width": width
+          "line-width": width,
+          ...dashArray ? { "line-dasharray": dashArray } : {}
         },
         type: "line"
       }
@@ -2783,6 +2793,7 @@ var MapInternal = ({
   pois = [],
   onPoiClick,
   route: externalRoute,
+  routeStyle,
   showNavigationUI: externalShowNavigationUI,
   navigationData: externalNavigationData,
   onNavigationAbort,
@@ -2807,6 +2818,7 @@ var MapInternal = ({
   const hasIntegratedNav = journey.isActive;
   const navigationData = hasIntegratedNav ? {
     currentDistanceMeters: journey.distanceRemainingMeters,
+    hasArrived: journey.hasArrived,
     mode: journey.mode,
     route: journey.route,
     start: journey.start,
@@ -2967,6 +2979,7 @@ var MapInternal = ({
   const showEtaData = showNavigationUI && navigationData && route ? {
     distanceRemainingKm: kmRemaining,
     etaMins,
+    hasArrived: navigationData.hasArrived ?? false,
     label: mode === "navigation" ? "Walking Guidance Active" : "Route Preview",
     mode,
     onAbort: () => {
@@ -3141,7 +3154,23 @@ var MapInternal = ({
             initialViewState,
             interactiveLayerIds: mergedInteractiveLayerIds,
             mapStyle,
-            maxBounds,
+            maxBounds: (
+              // @vis.gl/react-maplibre's own <Map> component (aliased MapLibre
+              // here) types maxBounds as a flat [west, south, east, north]
+              // tuple — raw maplibre-gl's LngLatBoundsLike still accepts a
+              // pair-of-corners shape, this narrowing is the wrapper's own.
+              // This SDK's public MapProps.maxBounds keeps the
+              // [[lng, lat], [lng, lat]] pair-of-corners shape (matches every
+              // other coordinate prop in this SDK, e.g. flyTo), so it's
+              // flattened here at the point of use rather than changing the
+              // public API.
+              maxBounds ? [
+                maxBounds[0][0],
+                maxBounds[0][1],
+                maxBounds[1][0],
+                maxBounds[1][1]
+              ] : void 0
+            ),
             onClick: handleMapClick,
             onContextMenu,
             onDragStart: handleUserInteraction,
@@ -3178,7 +3207,16 @@ var MapInternal = ({
                   radiusMeters: mockLocation.radiusMeters
                 }
               ),
-              displayRoute && /* @__PURE__ */ jsx16(RouteLayer, { geometry: displayRoute }),
+              displayRoute && /* @__PURE__ */ jsx16(
+                RouteLayer,
+                {
+                  color: routeStyle?.color,
+                  dashArray: routeStyle?.dashArray,
+                  geometry: displayRoute,
+                  opacity: routeStyle?.opacity,
+                  width: routeStyle?.width
+                }
+              ),
               pois.length > 0 && /* @__PURE__ */ jsxs12(Fragment5, { children: [
                 /* @__PURE__ */ jsx16(POILayers, { pois }),
                 /* @__PURE__ */ jsx16(POIMarkers, { onClick: onPoiClick, pois })
@@ -3403,7 +3441,7 @@ var loadImage2 = (src) => new Promise((resolve, reject) => {
 });
 
 // package.json
-var version = "0.8.0";
+var version = "0.9.0";
 
 // src/sdk.ts
 function deepFreeze(obj) {