expo-osm-sdk/build/hooks/useLocationTracking.d.ts

OpenStreetMap component for React Native with Expo

import React from 'react';
import { OSMViewRef, Coordinate } from '../types';
/**
 * Status of location tracking operations
 */
export type LocationTrackingStatus = 'idle' | 'starting' | 'active' | 'stopping' | 'error' | 'permission_required' | 'gps_disabled';
/**
 * Detailed error types for better handling
 */
export type LocationErrorType = 'permission_denied' | 'permission_restricted' | 'gps_disabled' | 'no_signal' | 'timeout' | 'view_not_ready' | 'unknown';
/**
 * Enhanced error information
 */
export interface LocationError {
    type: LocationErrorType;
    message: string;
    userMessage: string;
    canRetry: boolean;
    suggestedAction: string;
}
/**
 * Location tracking hook result
 */
export interface UseLocationTrackingResult {
    isTracking: boolean;
    status: LocationTrackingStatus;
    currentLocation: Coordinate | null;
    error: LocationError | null;
    startTracking: () => Promise<boolean>;
    stopTracking: () => Promise<boolean>;
    getCurrentLocation: () => Promise<Coordinate | null>;
    waitForLocation: (timeoutSeconds?: number) => Promise<Coordinate | null>;
    retryLastOperation: () => Promise<boolean>;
    clearError: () => void;
    getHealthStatus: () => Promise<LocationHealthStatus>;
}
/**
 * System health status
 */
export interface LocationHealthStatus {
    isSupported: boolean;
    hasPermission: boolean;
    isGpsEnabled: boolean;
    isViewReady: boolean;
    lastLocationAge: number | null;
    networkAvailable: boolean;
}
/**
 * Hook options
 */
export interface UseLocationTrackingOptions {
    autoStart?: boolean;
    onLocationChange?: (location: Coordinate) => void;
    onError?: (error: LocationError) => void;
    maxWaitTime?: number;
    maxRetryAttempts?: number;
    fallbackLocation?: Coordinate;
}
/**
 * Enhanced location tracking hook with bulletproof error handling
 *
 * This hook provides comprehensive error handling for all GPS and permission scenarios:
 * - Permission denied/revoked scenarios
 * - GPS disabled/unavailable
 * - No signal (indoor/underground)
 * - Timeout situations
 * - View lifecycle issues
 * - Network problems
 * - Hardware failures
 *
 * @param osmViewRef - Reference to the OSM view component
 * @param options - Hook configuration options
 * @returns Location tracking state and methods with comprehensive error handling
 *
 * @example
 * ```tsx
 * function MyMapComponent() {
 *   const mapRef = useRef<OSMViewRef>(null);
 *   const {
 *     isTracking,
 *     currentLocation,
 *     error,
 *     startTracking,
 *     stopTracking,
 *     getCurrentLocation,
 *     retryLastOperation,
 *     getHealthStatus
 *   } = useLocationTracking(mapRef, {
 *     maxRetryAttempts: 3,
 *     fallbackLocation: { latitude: 0, longitude: 0 },
 *     onError: (error) => {
 *       console.error('Location error:', error.userMessage);
 *       // Show user-friendly error message
 *       if (error.canRetry) {
 *         // Show retry button
 *       }
 *     }
 *   });
 *
 *   return (
 *     <View>
 *       <OSMView ref={mapRef} />
 *       {error && (
 *         <View>
 *           <Text>{error.userMessage}</Text>
 *           <Text>{error.suggestedAction}</Text>
 *           {error.canRetry && (
 *             <Button title="Retry" onPress={retryLastOperation} />
 *           )}
 *         </View>
 *       )}
 *     </View>
 *   );
 * }
 * ```
 */
export declare const useLocationTracking: (osmViewRef: React.RefObject<OSMViewRef>, options?: UseLocationTrackingOptions) => UseLocationTrackingResult;
//# sourceMappingURL=useLocationTracking.d.ts.map