@cloudparse/up-miniapps-sdk 0.2.6 → 0.5.2

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import React from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
 import { R as RouteResponse, a as RouteStep, b as RouteRequest, c as RoutingBackendConfig } from './index-B9dDciJq.js';
 export { C as ClearRouteRequest, D as DrawRouteRequest, h as handleClearRoute, d as handleDrawRoute, e as handleRouteRequest } from './index-B9dDciJq.js';
 import { ViewState } from '@vis.gl/react-maplibre';
@@ -18,7 +19,7 @@ interface BridgeMockerProps {
     simulationSpeed?: number;
     /** Mock JWT token for NETWORK_REQUEST mocking */
     mockJWTToken?: string;
-    children: React.ReactNode;
+    children: React__default.ReactNode;
 }
 /**
  * A utility component for Storybook that intercepts SDK bridge calls,
@@ -26,7 +27,7 @@ interface BridgeMockerProps {
  *
  * NOTE: Logs are now handled by the standalone DebugConsole component.
  */
-declare const BridgeMocker: React.FC<BridgeMockerProps>;
+declare const BridgeMocker: React__default.FC<BridgeMockerProps>;
 
 interface DebugConsoleProps {
     /**
@@ -43,7 +44,7 @@ interface DebugConsoleProps {
  * A standalone debug console that intercepts and displays all Bridge communication.
  * Useful for debugging both in mock mode (BridgeMocker) and on real devices.
  */
-declare const DebugConsole: React.FC<DebugConsoleProps>;
+declare const DebugConsole: React__default.FC<DebugConsoleProps>;
 
 /**
  * UP Mini-App SDK Types
@@ -468,7 +469,7 @@ type BridgeMessageType = {
 } | {
     type: "REQUEST_PERMISSION";
     payload: {
-        type: "location" | "profile";
+        type: "location" | "profile" | "camera";
         fields?: string[];
     };
     callbackId: string;
@@ -540,7 +541,7 @@ type BridgeMessageType = {
     callbackId: string;
 };
 
-type DrawerState = "closed" | "peek" | "full";
+type DrawerState = "closed" | "peek" | "full" | "auto";
 interface POI {
     id: string | number;
     name: string;
@@ -572,19 +573,19 @@ interface POI {
     /**
      * Optional custom React component when displayMode is 'marker'.
      */
-    markerComponent?: React.ReactNode;
+    markerComponent?: React__default.ReactNode;
 }
 interface MapProps {
     /** Initial view state of the map. */
     initialViewState?: Partial<ViewState>;
     /** Inline styles for the map container. */
-    style?: React.CSSProperties;
+    style?: React__default.CSSProperties;
     /** Minimum and maximum bounds for the map. */
     maxBounds?: [[number, number], [number, number]];
     /** MapLibre style URL. Defaults to local server. */
     mapStyle?: string;
     /** Children components (Source, Layer, etc.) */
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
     /** Additional CSS classes for the map container. */
     className?: string;
     /** Callback when the map is clicked. */
@@ -608,6 +609,14 @@ interface MapProps {
      * Note: The camera automatically locks when a route is provided.
      */
     followUser?: boolean;
+    /**
+     * Makes `followUser` an authoritative lock instead of a one-time initial
+     * default: manual pan/zoom/touch interaction will NOT disable tracking.
+     * Use for GPS-driven trackers/games where the camera must always follow
+     * the user; leave false (default) for browsable maps where the user is
+     * expected to pan away and press "Center on User" to come back.
+     */
+    lockToUser?: boolean;
     /**
      * Whether to show the built-in "Center on User" button.
      * Defaults to true.
@@ -620,7 +629,7 @@ interface MapProps {
     renderUserLocation?: (props: {
         coords: [number, number];
         heading: number | null;
-    }) => React.ReactNode;
+    }) => React__default.ReactNode;
     /** A list of POIs to display. */
     pois?: POI[];
     /** Callback when a POI is clicked. */
@@ -677,11 +686,11 @@ interface MapProps {
     /** Custom menu items to display in the vertical drawer. */
     menuItems?: MenuItem[];
     /** Custom React node to render inside the drawer menu container instead of menuItems list. */
-    menuContent?: React.ReactNode;
+    menuContent?: React__default.ReactNode;
     /** Programmatically control the drawer state. */
     drawerState?: DrawerState;
     /** Ref to the drawer's scrollable container. */
-    drawerContentRef?: React.Ref<HTMLDivElement>;
+    drawerContentRef?: React__default.Ref<HTMLDivElement>;
     /** Custom controls (e.g. buttons) to display floating above the recenter button. */
     controlProps?: MapControlsProps;
     /** Whether to enable touch drag gestures for the bottom sheet drawer. Defaults to false. */
@@ -690,14 +699,14 @@ interface MapProps {
 interface MenuItem {
     id: string;
     label: string;
-    icon: React.ReactNode;
+    icon: React__default.ReactNode;
     onPress: () => void;
     badge?: string | number;
     disabled?: boolean;
 }
 interface CustomControl {
     id: string;
-    icon: React.ReactNode;
+    icon: React__default.ReactNode;
     onPress: () => void;
     position: "above-recenter" | "below-recenter";
     tooltip?: string;
@@ -725,6 +734,18 @@ interface MapControlsState {
     isFollowing: boolean;
     setIsFollowing: (following: boolean) => void;
     centerOnUser: (params?: CenterCallbackParams) => void;
+    /**
+     * Fly the camera to an arbitrary [lng, lat] — e.g. jumping to a venue
+     * selected from a list. Unlike calling the raw MapLibre instance's own
+     * `flyTo` directly, this also disables follow-mode and locks out the
+     * "recenter on the user" live-location tracking for the duration of the
+     * animation, so a GPS update arriving mid-flight doesn't immediately snap
+     * the camera back to the user and undo it (this exact bug — flyTo only
+     * "worked" after the first manual pan, which is what actually disabled
+     * follow-mode — is why this exists instead of every consumer reaching
+     * into the MapLibre instance themselves).
+     */
+    flyTo: (coords: [number, number], params?: FlyToParams) => void;
     bearing: number;
     setBearing: (bearing: number) => void;
     pitch: number;
@@ -737,20 +758,45 @@ interface MapControlsState {
     drawerState: DrawerState;
     setDrawerState: (state: DrawerState) => void;
     /** Stable ref to the drawer's scrollable container. Always available. */
-    drawerContentRef: React.RefObject<HTMLDivElement | null>;
+    drawerContentRef: React__default.RefObject<HTMLDivElement | null>;
+    /**
+     * Show/hide the drawer's drag-handle bar programmatically — e.g. hide it
+     * while `menuContent` is itself a full-bleed swipeable detail view (its
+     * own drag handle/affordance would double up with the drawer's). Defaults
+     * to `true`. Remember to restore it (e.g. in a `useEffect` cleanup) when
+     * the content that needed it hidden unmounts.
+     */
+    drawerHandleVisible: boolean;
+    setDrawerHandleVisible: (visible: boolean) => void;
     insets: MapInsets;
     setInsets: (insets: Partial<MapInsets>) => void;
 }
 interface CenterCallbackParams {
     pitch?: number;
+    /**
+     * Optional bearing to animate to in the same motion as the center/zoom/pitch
+     * change. Pass this instead of calling `resetBearing()` right after
+     * `centerOnUser()` — two separate flyTo/easeTo calls on the same camera
+     * race each other (both touch pitch) and read as sluggish, multi-second
+     * drift instead of one clean fast motion.
+     */
+    bearing?: number;
+}
+interface FlyToParams {
+    zoom?: number;
+    pitch?: number;
+    bearing?: number;
+    /** ms. Defaults to MapLibre's own distance-based duration if omitted. */
+    duration?: number;
 }
 interface MapControlsContextType extends MapControlsState {
     _registerCenterCallback: (cb: (params?: CenterCallbackParams) => void) => void;
     _registerResetBearingCallback: (cb: (params?: CenterCallbackParams) => void) => void;
+    _registerFlyToCallback: (cb: (coords: [number, number], params?: FlyToParams) => void) => void;
 }
-declare const MapControlsContext: React.Context<MapControlsContextType | null>;
-declare const SDKMapProvider: React.FC<{
-    children: React.ReactNode;
+declare const MapControlsContext: React__default.Context<MapControlsContextType | null>;
+declare const SDKMapProvider: React__default.FC<{
+    children: React__default.ReactNode;
 }>;
 declare const useMapControls: () => MapControlsState;
 
@@ -758,8 +804,8 @@ interface MapControlsProps {
     menuItems?: MenuItem[];
     drawerSide?: "left" | "bottom";
     defaultState?: DrawerState;
-    menuContent?: React.ReactNode;
-    children?: React.ReactNode;
+    menuContent?: React__default.ReactNode;
+    children?: React__default.ReactNode;
     customControls?: CustomControl[];
     etaBarHeight?: number;
     onRecenter?: (params?: CenterCallbackParams) => void;
@@ -768,47 +814,56 @@ interface MapControlsProps {
     initialViewState?: Partial<ViewState>;
     onResetBearing?: (params?: CenterCallbackParams) => void;
     etaData?: EtaData;
-    customRecenterButton?: React.ReactNode;
-    customCompassButton?: React.ReactNode;
+    customRecenterButton?: React__default.ReactNode;
+    customCompassButton?: React__default.ReactNode;
     drawerPeekHeight?: string | number;
     drawerFullHeight?: string | number;
-    drawerContentRef?: React.Ref<HTMLDivElement>;
+    /**
+     * Max height the "auto" drawer state (sized to fit `menuContent`) can
+     * grow to. Default "100%" — the full available map container height
+     * (i.e. effectively 100vh), NOT `drawerFullHeight` (85% by default),
+     * so auto-sized content isn't clipped just because it's taller than the
+     * manual "full" state's height.
+     */
+    drawerAutoMaxHeight?: string | number;
+    drawerContentRef?: React__default.Ref<HTMLDivElement>;
     enableTouchDrag?: boolean;
     showScrollToTopButton?: boolean;
     scrollToTopThreshold?: number;
+    controlsBottomOffset?: number;
     isInternal?: boolean;
 }
-declare const MapControls: React.FC<MapControlsProps>;
+declare const MapControls: React__default.FC<MapControlsProps>;
 
 interface MapMenuProps {
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
 }
-declare const MapMenu: React.FC<MapMenuProps>;
+declare const MapMenu: React__default.FC<MapMenuProps>;
 interface MapMenuItemProps {
     id: string;
     label: string;
-    icon?: React.ReactNode;
+    icon?: React__default.ReactNode;
     onPress?: () => void;
     badge?: string | number;
     disabled?: boolean;
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
 }
-declare const MapMenuItem: React.FC<MapMenuItemProps>;
+declare const MapMenuItem: React__default.FC<MapMenuItemProps>;
 interface MapMenuTitleProps {
-    children: React.ReactNode;
+    children: React__default.ReactNode;
     className?: string;
     showDivider?: boolean;
 }
-declare const MapMenuTitle: React.FC<MapMenuTitleProps>;
+declare const MapMenuTitle: React__default.FC<MapMenuTitleProps>;
 interface MapMenuDividerProps {
     className?: string;
 }
-declare const MapMenuDivider: React.FC<MapMenuDividerProps>;
+declare const MapMenuDivider: React__default.FC<MapMenuDividerProps>;
 interface MapMenuFooterProps {
-    children: React.ReactNode;
+    children: React__default.ReactNode;
     className?: string;
 }
-declare const MapMenuFooter: React.FC<MapMenuFooterProps>;
+declare const MapMenuFooter: React__default.FC<MapMenuFooterProps>;
 
 interface LiveRoutingOptions {
     /** Origin coordinates [lng, lat]. If not provided, uses device location. */
@@ -858,6 +913,72 @@ declare const useRoute: (origin: [number, number] | null, destination: [number,
     } | null | undefined;
 };
 
+type NavMode = "preview" | "navigation";
+interface DeclarativeJourneyOptions {
+    /** Destination coordinates [lng, lat] */
+    destination: [number, number] | null;
+    /** Transport profile. Defaults to 'driving'. */
+    profile?: LiveRoutingOptions["profile"];
+    /** Minimum distance in meters the user must move before recalculating path geometry. Defaults to 50. */
+    recalculateThreshold?: number;
+    /** Optional manual origin. Defaults to real-time user location. */
+    origin?: [number, number] | null;
+    /** Initial mode. 'preview' shows the route overview, 'navigation' starts active guidance. Defaults to 'preview'. */
+    mode?: NavMode;
+}
+interface UseJourneyOptions {
+    /**
+     * Declarative journey configuration. If provided, this hook manages route
+     * calculation/tracking itself — equivalent to the `navigation` prop on `<Map/>`.
+     * Omit this to instead drive the journey imperatively via `sdk.navigation.*`
+     * (createJourney/start/abort), e.g. from elsewhere in the app or from `<Map/>` itself.
+     */
+    navigation?: DeclarativeJourneyOptions;
+    /** Called whenever the journey is cancelled/aborted. */
+    onAbort?: () => void;
+    /** Called whenever the mode changes (e.g. preview -> navigation). */
+    onModeChange?: (mode: NavMode) => void;
+}
+interface UseJourneyResult {
+    /** Whether a journey (preview or navigation) is currently active. */
+    isActive: boolean;
+    /** Current mode: 'preview' (route overview) or 'navigation' (active guidance). */
+    mode: NavMode;
+    /** The calculated route geometry/data, or null if none. */
+    route: RouteResponse["data"] | null;
+    /** Whether a route calculation is in flight. */
+    isCalculating: boolean;
+    /** Routing error message, if any. */
+    error: string | null;
+    /** Real-time remaining distance to destination, in meters. */
+    distanceRemainingMeters: number | null;
+    /** Real-time remaining distance to destination, in kilometers. */
+    distanceRemainingKm: number;
+    /** The total distance of the route when the destination was first set, in meters. */
+    totalDistanceMeters: number | null;
+    /** Estimated remaining time, in minutes, scaled proportionally to remaining distance. */
+    etaMinutes: number;
+    /** Journey completion progress, 0-100. */
+    progress: number;
+    /** Switch from 'preview' to active 'navigation' guidance. */
+    start: () => void;
+    /** Cancel the journey entirely. Always returns to 'preview' the next time a journey starts. */
+    cancel: () => void;
+    /** Force a manual route recalculation. */
+    recalculate: () => void;
+}
+/**
+ * Everything related to a map journey — preview, active navigation, and ETA —
+ * exposed as plain data and actions so devs can build their own preview/journey
+ * panel instead of using the SDK's built-in one.
+ *
+ * Stays in sync with `<Map/>`'s built-in navigation UI: both this hook and
+ * `<Map/>` react to the same `sdk.navigation.*` imperative events, so you can
+ * use `useJourney()` to drive a fully custom UI while `<Map/>` handles the
+ * route line/camera, or use it standalone with the `navigation` option.
+ */
+declare const useJourney: (options?: UseJourneyOptions) => UseJourneyResult;
+
 /**
  * Slices a LineString to start at the point closest to the provided coordinates.
  * This removes the "already traveled" portion of the route.
@@ -881,9 +1002,28 @@ interface RouteLayerProps {
     /** Opacity of the route line. Defaults to 0.8. */
     opacity?: number;
 }
-declare const RouteLayer: React.FC<RouteLayerProps>;
+declare const RouteLayer: React__default.FC<RouteLayerProps>;
+
+declare const Map: React__default.FC<MapProps>;
 
-declare const Map: React.FC<MapProps>;
+interface MockLocationContextType {
+    /** Radius in meters to draw around the mocked user location. 0 hides it. */
+    radiusMeters: number;
+    /** When true, the next map click drops the mocked location there instead
+     * of firing the app's own onClick/onMapClickMiss handlers. */
+    isPlacingLocation: boolean;
+    /** Called by the Map when a click lands while isPlacingLocation is true. */
+    placeLocation: (coords: [number, number]) => void;
+}
+/**
+ * Bridges BridgeMocker (owns the mocked location/radius state, rendered as
+ * a sibling dev panel outside the map's DOM tree) and the Map component
+ * (needs to read that state to draw the radius overlay and intercept
+ * "drop location here" clicks) without prop-drilling through every
+ * consumer app's own Map usage.
+ */
+declare const MockLocationContext: React.Context<MockLocationContextType | null>;
+declare const useMockLocation: () => MockLocationContextType | null;
 
 /**
  * Renders the Map component into a DOM element.
@@ -901,7 +1041,7 @@ declare function renderMap(containerId: string, props?: MapProps): react_dom_cli
  */
 declare const useIsMocked: () => boolean;
 interface SDKProviderProps extends Partial<Omit<BridgeMockerProps, "children">> {
-    children: React.ReactNode;
+    children: React__default.ReactNode;
     /**
      * If true, shows the standalone DebugConsole for bridge traffic.
      */
@@ -911,7 +1051,64 @@ interface SDKProviderProps extends Partial<Omit<BridgeMockerProps, "children">>
  * A wrapper component that automatically enables the BridgeMocker
  * when running outside the native shell app.
  */
-declare const SDKProvider: React.FC<SDKProviderProps>;
+declare const SDKProvider: React__default.FC<SDKProviderProps>;
+
+type SwipeAxisPriority = "horizontal" | "vertical";
+interface SwipeCarouselItem {
+    id: string;
+    content: ReactNode;
+    className?: string;
+}
+interface SwipeCarouselVerticalDragConfig {
+    /** Which way the active slide may be dragged. Default "down". */
+    direction?: "down" | "up" | "both";
+    /** px past which releasing fires onDismiss. Default 200. */
+    dismissThreshold?: number;
+    /** px/ms past which releasing fires onDismiss regardless of distance. Default 0.5. */
+    dismissVelocity?: number;
+    /**
+     * Vertical tracking only starts when the touch begins inside an element
+     * matching this selector AND that element is scrolled to its top
+     * (scrollTop <= 2) — lets normal content scrolling take priority
+     * otherwise. Default `[data-swipe-scroll-root]`; mark the scrollable
+     * content root inside each slide with that attribute.
+     */
+    scrollRootSelector?: string;
+    /** Fires on every move once vertical drag is engaged, with the raw px offset (already past the small dead-zone), and once more with `(0, false)` on release. */
+    onDragChange?: (deltaY: number, isDragging: boolean) => void;
+    /** Fires once, on release, when the drag crossed the dismiss threshold. */
+    onDismiss?: () => void;
+}
+interface SwipeCarouselProps {
+    items: SwipeCarouselItem[];
+    activeId: string | null;
+    onActiveChange: (id: string) => void;
+    /** How many slides fit across the viewport (1.1 == active slide + a sliver of its neighbor). */
+    peek?: number;
+    gap?: number;
+    className?: string;
+    itemClassName?: string;
+    /**
+     * Once a touch moves past the direction-lock threshold, the dominant axis
+     * (bigger |dx| vs |dy|) wins the WHOLE gesture — the other axis is frozen
+     * for the rest of that touch, so a horizontal swipe can't also drag the
+     * slide down and vice versa. `axisPriority` only breaks an exact tie at
+     * that decision point. Default "horizontal".
+     */
+    axisPriority?: SwipeAxisPriority;
+    /** Enables swipe-to-dismiss on the ACTIVE slide only (e.g. drag-down-to-close a detail sheet). Omit for a pure horizontal carousel. */
+    verticalDrag?: SwipeCarouselVerticalDragConfig;
+    /** Slides kept MOUNTED on each side of the active one, so a 100+ item list stays cheap and the next swipe target is already in the DOM. Default 2 (5 slides mounted total). */
+    overscan?: number;
+    /**
+     * Slides kept VISIBLE (opacity) on each side of the active one — must be
+     * <= `overscan`. Slides beyond this stay mounted (for an instant, already-
+     * positioned reveal once they enter range) but invisible, so their
+     * shadow/blur styling can't bleed into the visible strip. Default 1.
+     */
+    visibleOverscan?: number;
+}
+declare const SwipeCarousel: ({ items, activeId, onActiveChange, peek, gap, className, itemClassName, axisPriority, verticalDrag, overscan, visibleOverscan, }: SwipeCarouselProps) => React.JSX.Element;
 
 declare class MiniAppSDK {
     /**
@@ -1092,8 +1289,13 @@ declare class MiniAppSDK {
         getFidelityHistory: (params?: IFidelityHistoryParams) => Promise<IFidelityTransaction[]>;
         /**
          * Triggers the native fidelity history view.
+         * @param options.isDark Theme to render the native view in. Pass the
+         * mini-app's current theme explicitly — the native history screen is a
+         * standalone view and does not read it from `updateContext`.
          */
-        showHistory: () => Promise<void>;
+        showHistory: (options?: {
+            isDark?: boolean;
+        }) => Promise<void>;
         /**
          * Authorize spending fidelity points (FPoints) via Two-Phase Authorization.
          * @param intentUuid UUID generated by your backend for the transaction.
@@ -1183,4 +1385,4 @@ declare class MiniAppSDK {
  */
 declare const sdk: MiniAppSDK;
 
-export { type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type CenterCallbackParams, type CustomControl, DebugConsole, type DebugConsoleProps, type DrawerState, type EtaData, type FidelityTransactionTypeType, GeolocationEvent, GlobalEvent, type HapticStyleType, type IBridgeEnvelope, type IContextState, type IEdgeInsets, type IFidelityBalance, type IFidelityHistoryParams, type IFidelityTransaction, type IInitializationOptions, type IInitializationResponse, type ILocationData, type INetworkOptions, type INetworkResponse, type IPaymentRequest, type IUserProfile, type LiveRoutingOptions, type LiveRoutingResult, type LocationStreamConfig, Map, MapControls, MapControlsContext, type MapControlsProps, type MapControlsState, type MapInsets, MapMenu, MapMenuDivider, type MapMenuDividerProps, MapMenuFooter, type MapMenuFooterProps, MapMenuItem, type MapMenuItemProps, type MapMenuProps, MapMenuTitle, type MapMenuTitleProps, type MapProps, type MenuItem, MiniAppSDK, type NetworkMethodType, type POI, RouteLayer, type RouteLayerProps, RouteRequest, RouteResponse, RouteStep, type SDKEvent, SDKMapProvider, SDKProvider, type SDKProviderProps, type ScrollConfig, type StreamAccelerometerData, type StreamHeadingData, type StreamLocationData, type StreamUpdatePayload, UIEvent, type UserLocationState, sdk as default, renderMap, sdk, useIsMocked, useLiveRouting, useMapControls, useRoute, useTrimmedRoute, useUserLocation };
+export { type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type CenterCallbackParams, type CustomControl, DebugConsole, type DebugConsoleProps, type DeclarativeJourneyOptions, type DrawerState, type EtaData, type FidelityTransactionTypeType, type FlyToParams, GeolocationEvent, GlobalEvent, type HapticStyleType, type IBridgeEnvelope, type IContextState, type IEdgeInsets, type IFidelityBalance, type IFidelityHistoryParams, type IFidelityTransaction, type IInitializationOptions, type IInitializationResponse, type ILocationData, type INetworkOptions, type INetworkResponse, type IPaymentRequest, type IUserProfile, type LiveRoutingOptions, type LiveRoutingResult, type LocationStreamConfig, Map, MapControls, MapControlsContext, type MapControlsProps, type MapControlsState, type MapInsets, MapMenu, MapMenuDivider, type MapMenuDividerProps, MapMenuFooter, type MapMenuFooterProps, MapMenuItem, type MapMenuItemProps, type MapMenuProps, MapMenuTitle, type MapMenuTitleProps, type MapProps, type MenuItem, MiniAppSDK, MockLocationContext, type MockLocationContextType, type NetworkMethodType, type POI, RouteLayer, type RouteLayerProps, RouteRequest, RouteResponse, RouteStep, type SDKEvent, SDKMapProvider, SDKProvider, type SDKProviderProps, type ScrollConfig, type StreamAccelerometerData, type StreamHeadingData, type StreamLocationData, type StreamUpdatePayload, type SwipeAxisPriority, SwipeCarousel, type SwipeCarouselItem, type SwipeCarouselProps, type SwipeCarouselVerticalDragConfig, UIEvent, type UseJourneyOptions, type UseJourneyResult, type UserLocationState, sdk as default, renderMap, sdk, useIsMocked, useJourney, useLiveRouting, useMapControls, useMockLocation, useRoute, useTrimmedRoute, useUserLocation };