@ingissa/navcore-react-native 1.0.8 → 1.0.9

package/dist/index.d.mts

@@ -0,0 +1,131 @@
+import { Coordinate, NavInstruction, NavCoreOptions, NavCoreState, NavCore } from '@ingissa/navcore-core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * useNavCore — React hook for the NavCore navigation engine.
+ *
+ * Manages engine lifecycle, GPS → engine → state pipeline,
+ * event wiring, and optimized re-render batching.
+ *
+ * Drop-in replacement for the existing Go4Exams useNavCore hook.
+ */
+
+interface UseNavCoreProps {
+    /** Current GPS coordinate [lng, lat] */
+    gpsCoord: Coordinate | null;
+    /** GPS bearing in degrees */
+    gpsBearing?: number | null;
+    /** GPS accuracy in metres */
+    gpsAccuracy?: number | null;
+    /** GPS timestamp (ms since epoch) */
+    gpsTimestamp?: number | null;
+    /** Current speed in m/s */
+    speed: number;
+    /** Route geometry [lng, lat][] */
+    routeGeometry: Coordinate[] | null;
+    /** Navigation instructions */
+    instructions?: NavInstruction[];
+    /** Whether navigation has been started by the user */
+    isNavigating: boolean;
+    /** Engine configuration */
+    options?: NavCoreOptions;
+    /** Resume navigation at a specific route index (after rejoin) */
+    resumeAtIndex?: number | null;
+    /** Ref for external camera output (map camera integration) */
+    outputRef?: {
+        current: {
+            coord: Coordinate;
+            bearing: number;
+            speed: number;
+        } | null;
+    };
+    /** Called when deviation is confirmed */
+    onDeviation?: (event: {
+        anchorIndex: number;
+        ghostCoord: Coordinate;
+    }) => void;
+    /** Called when rejoin completes */
+    onRejoin?: (event: {
+        resumeIndex: number;
+    }) => void;
+    /** Called when an instruction triggers */
+    onInstruction?: (instruction: NavInstruction) => void;
+    /** Called when arrival is detected */
+    onArrival?: () => void;
+    /** UI polling rate in Hz (default 30) */
+    pollRateHz?: number;
+}
+interface UseNavCoreReturn extends NavCoreState {
+    /** The raw NavCore engine instance (for advanced usage) */
+    engine: NavCore;
+}
+declare function useNavCore({ gpsCoord, gpsBearing, gpsAccuracy, gpsTimestamp, speed, routeGeometry, instructions, isNavigating, options, resumeAtIndex, outputRef, onDeviation, onRejoin, onInstruction, onArrival, pollRateHz, }: UseNavCoreProps): UseNavCoreReturn;
+
+interface NavCoreContextValue {
+    engine: NavCore;
+}
+interface NavCoreProviderProps {
+    children: ReactNode;
+    options?: NavCoreOptions;
+}
+/**
+ * Wraps children with a shared NavCore engine instance.
+ *
+ * ```tsx
+ * <NavCoreProvider options={{ licenseKey: '...' }}>
+ *   <MapScreen />
+ *   <InstructionBanner />
+ * </NavCoreProvider>
+ * ```
+ */
+declare function NavCoreProvider({ children, options }: NavCoreProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the shared NavCore engine from context.
+ * Must be used within a <NavCoreProvider>.
+ */
+declare function useNavCoreContext(): NavCoreContextValue;
+
+/**
+ * Granular selector hooks for NavCore.
+ *
+ * Built with React 18 `useSyncExternalStore` for flicker-free, tearing-free
+ * state subscriptions. Components only re-render when the selected slice changes.
+ */
+
+/**
+ * Generic reactive selector subscribing to NavCore state updates.
+ * Only triggers re-renders when the selected value actually changes.
+ */
+declare function useNavSelector<T>(selector: (state: NavCoreState) => T, customEngine?: NavCore, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * Hook to select the current upcoming turn-by-turn navigation instruction.
+ * Only re-renders when the instruction changes or triggers.
+ */
+declare function useNavInstruction(customEngine?: NavCore): NavInstruction | null;
+/**
+ * Hook to select current alert/deviation state ('NONE' | 'DEVIATING' | 'RECALCULATING' | 'REJOINING' | 'REJOINED').
+ * Only re-renders on alert state transitions.
+ */
+declare function useNavAlert(customEngine?: NavCore): NavCoreState['alertState'];
+interface NavProgressInfo {
+    distanceToDestination: number | null;
+    distanceToNextInstruction: number | null;
+    progressIndex: number;
+    routeIndex: number;
+    hasArrived: boolean;
+}
+/**
+ * Hook to select navigation progress and remaining distance metrics.
+ */
+declare function useNavProgress(customEngine?: NavCore): NavProgressInfo;
+/**
+ * Hook to select whether the vehicle is currently off-route.
+ */
+declare function useNavIsOffRoute(customEngine?: NavCore): boolean;
+/**
+ * Hook to select current speed in m/s.
+ */
+declare function useNavSpeed(customEngine?: NavCore): number;
+
+export { NavCoreProvider, type NavProgressInfo, type UseNavCoreProps, type UseNavCoreReturn, useNavAlert, useNavCore, useNavCoreContext, useNavInstruction, useNavIsOffRoute, useNavProgress, useNavSelector, useNavSpeed };

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import { Coordinate, NavInstruction, NavCoreOptions, NavCoreState, NavCore } from '@ingissa/navcore-core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * useNavCore — React hook for the NavCore navigation engine.
+ *
+ * Manages engine lifecycle, GPS → engine → state pipeline,
+ * event wiring, and optimized re-render batching.
+ *
+ * Drop-in replacement for the existing Go4Exams useNavCore hook.
+ */
+
+interface UseNavCoreProps {
+    /** Current GPS coordinate [lng, lat] */
+    gpsCoord: Coordinate | null;
+    /** GPS bearing in degrees */
+    gpsBearing?: number | null;
+    /** GPS accuracy in metres */
+    gpsAccuracy?: number | null;
+    /** GPS timestamp (ms since epoch) */
+    gpsTimestamp?: number | null;
+    /** Current speed in m/s */
+    speed: number;
+    /** Route geometry [lng, lat][] */
+    routeGeometry: Coordinate[] | null;
+    /** Navigation instructions */
+    instructions?: NavInstruction[];
+    /** Whether navigation has been started by the user */
+    isNavigating: boolean;
+    /** Engine configuration */
+    options?: NavCoreOptions;
+    /** Resume navigation at a specific route index (after rejoin) */
+    resumeAtIndex?: number | null;
+    /** Ref for external camera output (map camera integration) */
+    outputRef?: {
+        current: {
+            coord: Coordinate;
+            bearing: number;
+            speed: number;
+        } | null;
+    };
+    /** Called when deviation is confirmed */
+    onDeviation?: (event: {
+        anchorIndex: number;
+        ghostCoord: Coordinate;
+    }) => void;
+    /** Called when rejoin completes */
+    onRejoin?: (event: {
+        resumeIndex: number;
+    }) => void;
+    /** Called when an instruction triggers */
+    onInstruction?: (instruction: NavInstruction) => void;
+    /** Called when arrival is detected */
+    onArrival?: () => void;
+    /** UI polling rate in Hz (default 30) */
+    pollRateHz?: number;
+}
+interface UseNavCoreReturn extends NavCoreState {
+    /** The raw NavCore engine instance (for advanced usage) */
+    engine: NavCore;
+}
+declare function useNavCore({ gpsCoord, gpsBearing, gpsAccuracy, gpsTimestamp, speed, routeGeometry, instructions, isNavigating, options, resumeAtIndex, outputRef, onDeviation, onRejoin, onInstruction, onArrival, pollRateHz, }: UseNavCoreProps): UseNavCoreReturn;
+
+interface NavCoreContextValue {
+    engine: NavCore;
+}
+interface NavCoreProviderProps {
+    children: ReactNode;
+    options?: NavCoreOptions;
+}
+/**
+ * Wraps children with a shared NavCore engine instance.
+ *
+ * ```tsx
+ * <NavCoreProvider options={{ licenseKey: '...' }}>
+ *   <MapScreen />
+ *   <InstructionBanner />
+ * </NavCoreProvider>
+ * ```
+ */
+declare function NavCoreProvider({ children, options }: NavCoreProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the shared NavCore engine from context.
+ * Must be used within a <NavCoreProvider>.
+ */
+declare function useNavCoreContext(): NavCoreContextValue;
+
+/**
+ * Granular selector hooks for NavCore.
+ *
+ * Built with React 18 `useSyncExternalStore` for flicker-free, tearing-free
+ * state subscriptions. Components only re-render when the selected slice changes.
+ */
+
+/**
+ * Generic reactive selector subscribing to NavCore state updates.
+ * Only triggers re-renders when the selected value actually changes.
+ */
+declare function useNavSelector<T>(selector: (state: NavCoreState) => T, customEngine?: NavCore, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * Hook to select the current upcoming turn-by-turn navigation instruction.
+ * Only re-renders when the instruction changes or triggers.
+ */
+declare function useNavInstruction(customEngine?: NavCore): NavInstruction | null;
+/**
+ * Hook to select current alert/deviation state ('NONE' | 'DEVIATING' | 'RECALCULATING' | 'REJOINING' | 'REJOINED').
+ * Only re-renders on alert state transitions.
+ */
+declare function useNavAlert(customEngine?: NavCore): NavCoreState['alertState'];
+interface NavProgressInfo {
+    distanceToDestination: number | null;
+    distanceToNextInstruction: number | null;
+    progressIndex: number;
+    routeIndex: number;
+    hasArrived: boolean;
+}
+/**
+ * Hook to select navigation progress and remaining distance metrics.
+ */
+declare function useNavProgress(customEngine?: NavCore): NavProgressInfo;
+/**
+ * Hook to select whether the vehicle is currently off-route.
+ */
+declare function useNavIsOffRoute(customEngine?: NavCore): boolean;
+/**
+ * Hook to select current speed in m/s.
+ */
+declare function useNavSpeed(customEngine?: NavCore): number;
+
+export { NavCoreProvider, type NavProgressInfo, type UseNavCoreProps, type UseNavCoreReturn, useNavAlert, useNavCore, useNavCoreContext, useNavInstruction, useNavIsOffRoute, useNavProgress, useNavSelector, useNavSpeed };

package/dist/index.js

@@ -0,0 +1,233 @@
+'use strict';
+
+var react = require('react');
+var navcoreCore = require('@ingissa/navcore-core');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/useNavCore.ts
+function useNavCore({
+  gpsCoord,
+  gpsBearing,
+  gpsAccuracy,
+  gpsTimestamp,
+  speed,
+  routeGeometry,
+  instructions,
+  isNavigating,
+  options,
+  resumeAtIndex,
+  outputRef,
+  onDeviation,
+  onRejoin,
+  onInstruction,
+  onArrival,
+  pollRateHz = 30
+}) {
+  const navRef = react.useRef(null);
+  if (!navRef.current) {
+    navRef.current = new navcoreCore.NavCore(options);
+  }
+  const engine = navRef.current;
+  const [state, setState] = react.useState(() => engine.getState());
+  react.useEffect(() => {
+    if (!onDeviation) return;
+    const handler = (data) => onDeviation(data);
+    engine.on("deviation", handler);
+    return () => {
+      engine.off("deviation", handler);
+    };
+  }, [engine, onDeviation]);
+  react.useEffect(() => {
+    if (!onRejoin) return;
+    const handler = (data) => onRejoin(data);
+    engine.on("rejoined", handler);
+    return () => {
+      engine.off("rejoined", handler);
+    };
+  }, [engine, onRejoin]);
+  react.useEffect(() => {
+    if (!onInstruction) return;
+    const handler = (data) => onInstruction(data);
+    engine.on("instruction", handler);
+    return () => {
+      engine.off("instruction", handler);
+    };
+  }, [engine, onInstruction]);
+  react.useEffect(() => {
+    if (!onArrival) return;
+    const handler = () => onArrival();
+    engine.on("arrival", handler);
+    return () => {
+      engine.off("arrival", handler);
+    };
+  }, [engine, onArrival]);
+  react.useEffect(() => {
+    if (routeGeometry && routeGeometry.length >= 2) {
+      engine.setRoute(routeGeometry, instructions);
+    }
+  }, [engine, routeGeometry]);
+  react.useEffect(() => {
+    if (instructions && instructions.length > 0 && routeGeometry && routeGeometry.length >= 2) {
+      engine.setRoute(routeGeometry, instructions);
+    }
+  }, [engine, instructions]);
+  react.useEffect(() => {
+    if (!gpsCoord || !isNavigating) return;
+    const gpsUpdate = {
+      coord: gpsCoord,
+      accuracy: gpsAccuracy ?? null,
+      bearing: gpsBearing ?? null,
+      speed,
+      timestamp: gpsTimestamp ?? Date.now()
+    };
+    const nextState = engine.update(gpsUpdate);
+    if (outputRef) {
+      outputRef.current = {
+        coord: nextState.snappedCoord ?? gpsCoord,
+        bearing: nextState.bearing,
+        speed: nextState.currentSpeed
+      };
+    }
+  }, [engine, gpsCoord, gpsAccuracy, gpsBearing, gpsTimestamp, speed, isNavigating, outputRef]);
+  react.useEffect(() => {
+    if (isNavigating) {
+      engine.startNavigation();
+    }
+  }, [engine, isNavigating]);
+  react.useEffect(() => {
+    if (!isNavigating) return;
+    const handleUpdate = (updatedState) => {
+      setState(updatedState);
+    };
+    engine.on("update", handleUpdate);
+    setState(engine.getState());
+    return () => {
+      engine.off("update", handleUpdate);
+    };
+  }, [engine, isNavigating]);
+  react.useEffect(() => {
+    return () => {
+      engine.destroy();
+      navRef.current = null;
+    };
+  }, [engine]);
+  return react.useMemo(() => ({
+    ...state,
+    engine
+  }), [state, engine]);
+}
+var NavCoreContext = react.createContext(null);
+function NavCoreProvider({ children, options }) {
+  const engineRef = react.useRef(null);
+  if (!engineRef.current) {
+    engineRef.current = new navcoreCore.NavCore(options);
+  }
+  const value = react.useMemo(() => ({
+    engine: engineRef.current
+  }), []);
+  return /* @__PURE__ */ jsxRuntime.jsx(NavCoreContext.Provider, { value, children });
+}
+function useNavCoreContext() {
+  const ctx = react.useContext(NavCoreContext);
+  if (!ctx) {
+    throw new Error("useNavCoreContext must be used within a <NavCoreProvider>");
+  }
+  return ctx;
+}
+function useNavSelector(selector, customEngine, isEqual = Object.is) {
+  let contextEngine;
+  try {
+    contextEngine = useNavCoreContext().engine;
+  } catch {
+    contextEngine = void 0;
+  }
+  const engine = customEngine ?? contextEngine;
+  if (!engine) {
+    throw new Error("useNavSelector must be provided an engine or used within a NavCoreProvider");
+  }
+  const lastSelectedRef = react.useRef(void 0);
+  const lastStateRef = react.useRef(void 0);
+  const getSnapshot = react.useCallback(() => {
+    const currentState = engine.getState();
+    if (lastStateRef.current === currentState && lastSelectedRef.current !== void 0) {
+      return lastSelectedRef.current;
+    }
+    const nextSelected = selector(currentState);
+    if (lastSelectedRef.current !== void 0 && isEqual(lastSelectedRef.current, nextSelected)) {
+      return lastSelectedRef.current;
+    }
+    lastStateRef.current = currentState;
+    lastSelectedRef.current = nextSelected;
+    return nextSelected;
+  }, [engine, selector, isEqual]);
+  const subscribe = react.useCallback((onStoreChange) => {
+    engine.on("update", onStoreChange);
+    return () => {
+      engine.off("update", onStoreChange);
+    };
+  }, [engine]);
+  return react.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function useNavInstruction(customEngine) {
+  return useNavSelector(
+    (state) => {
+      if (state.nextInstructionIndex === null) return null;
+      let engine = customEngine;
+      if (!engine) {
+        try {
+          engine = useNavCoreContext().engine;
+        } catch {
+        }
+      }
+      if (!engine) return null;
+      const list = engine.getInstructions();
+      return list[state.nextInstructionIndex] ?? null;
+    },
+    customEngine,
+    (a, b) => a === b || a?.geometryIndex === b?.geometryIndex && a?.instruction === b?.instruction
+  );
+}
+function useNavAlert(customEngine) {
+  return useNavSelector(
+    (state) => state.alertState,
+    customEngine,
+    Object.is
+  );
+}
+function useNavProgress(customEngine) {
+  return useNavSelector(
+    (state) => ({
+      distanceToDestination: state.distanceToDestination,
+      distanceToNextInstruction: state.distanceToNextInstruction,
+      progressIndex: state.progressIndex,
+      routeIndex: state.routeIndex,
+      hasArrived: state.hasArrived
+    }),
+    customEngine,
+    (a, b) => a.distanceToDestination === b.distanceToDestination && a.distanceToNextInstruction === b.distanceToNextInstruction && a.progressIndex === b.progressIndex && a.routeIndex === b.routeIndex && a.hasArrived === b.hasArrived
+  );
+}
+function useNavIsOffRoute(customEngine) {
+  return useNavSelector(
+    (state) => state.isOffRoute,
+    customEngine,
+    Object.is
+  );
+}
+function useNavSpeed(customEngine) {
+  return useNavSelector(
+    (state) => state.currentSpeed,
+    customEngine,
+    Object.is
+  );
+}
+
+exports.NavCoreProvider = NavCoreProvider;
+exports.useNavAlert = useNavAlert;
+exports.useNavCore = useNavCore;
+exports.useNavCoreContext = useNavCoreContext;
+exports.useNavInstruction = useNavInstruction;
+exports.useNavIsOffRoute = useNavIsOffRoute;
+exports.useNavProgress = useNavProgress;
+exports.useNavSelector = useNavSelector;
+exports.useNavSpeed = useNavSpeed;