@ingissa/navcore-react-native 1.0.8 → 1.0.10

package/LICENSE

@@ -1,3 +1,3 @@
-Copyright (c) 2026 Abdelnasser Aitabi. All rights reserved.
-
-No license is granted except by separate written agreement.
+Copyright (c) 2026 Abdelnasser Aitabi. All rights reserved.
+
+No license is granted except by separate written agreement.

package/README.md

@@ -0,0 +1,135 @@
+# @ingissa/navcore-react-native
+
+[Official Website](https://navcore-web.vercel.app/)
+
+> React Native bindings and state selectors for the NavCore navigation engine.
+
+[![npm version](https://img.shields.io/npm/v/@ingissa/navcore-react-native)](https://www.npmjs.com/package/@ingissa/navcore-react-native)
+![License](https://img.shields.io/badge/license-Proprietary-red)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
+
+---
+
+## Overview
+
+`@ingissa/navcore-react-native` provides lightweight, tearing-free React bindings for NavCore. Built on React 18's `useSyncExternalStore`, components subscribe to granular slices of navigation state and only re-render when their specific slice changes.
+
+### Key Features
+- **Zero native binary modules**: Pure JavaScript/TypeScript layer that works seamlessly with Expo Go, Expo Prebuild, and bare React Native.
+- **Granular selector hooks**: Prevent full-screen re-renders on high-frequency (1–10 Hz) GPS ticks.
+- **Shared engine context**: Easily share a single `NavCore` engine instance across maps, HUD banners, speedometers, and debug overlays using `NavCoreProvider`.
+
+---
+
+## Installation
+
+```bash
+npm install @ingissa/navcore-react-native @ingissa/navcore-core
+```
+
+### Peer Dependencies
+- `@ingissa/navcore-core`: `^1.0.9` (required)
+- `react`: `>=18.0.0` (required)
+- `react-native`: `>=0.72.0` (required)
+- `react-native-maps`: `>=1.0.0` (optional, for applications using React Native Maps)
+
+---
+
+## Quickstart
+
+### 1. Wrap your navigation screens in `NavCoreProvider`
+
+```tsx
+import React from 'react';
+import { NavCoreProvider } from '@ingissa/navcore-react-native';
+import { NavigationScreen } from './NavigationScreen';
+
+export function App() {
+  return (
+    <NavCoreProvider options={{ isDev: true }}>
+      <NavigationScreen />
+    </NavCoreProvider>
+  );
+}
+```
+
+### 2. Consume granular state in child components
+
+```tsx
+import React from 'react';
+import { View, Text } from 'react-native';
+import {
+  useNavInstruction,
+  useNavProgress,
+  useNavSpeed,
+  useNavIsOffRoute,
+} from '@ingissa/navcore-react-native';
+
+export function NavigationHud() {
+  const instruction = useNavInstruction();
+  const { distanceToDestination, distanceToNextInstruction } = useNavProgress();
+  const speed = useNavSpeed();
+  const isOffRoute = useNavIsOffRoute();
+
+  return (
+    <View style={{ padding: 16, backgroundColor: '#111', borderRadius: 8 }}>
+      {isOffRoute && <Text style={{ color: 'red' }}>⚠️ Off Route - Recalculating</Text>}
+      <Text style={{ color: 'white', fontSize: 18 }}>
+        {instruction?.text ?? 'Continue on route'}
+      </Text>
+      <Text style={{ color: '#aaa' }}>
+        In {distanceToNextInstruction != null ? `${Math.round(distanceToNextInstruction)}m` : '—'}
+      </Text>
+      <Text style={{ color: '#aaa' }}>
+        Destination: {distanceToDestination != null ? `${(distanceToDestination / 1000).toFixed(1)}km` : '—'}
+      </Text>
+      <Text style={{ color: '#4ade80' }}>
+        Speed: {Math.round(speed * 3.6)} km/h
+      </Text>
+    </View>
+  );
+}
+```
+
+### 3. Custom Selective Re-renders with `useNavSelector`
+
+```tsx
+import { useNavSelector } from '@ingissa/navcore-react-native';
+
+// Only re-renders when alertState ('NONE' | 'DEVIATING' | 'RECALCULATING' | 'REJOINING' | 'REJOINED') changes
+export function AlertBadge() {
+  const alertState = useNavSelector((state) => state.alertState);
+  if (alertState === 'NONE') return null;
+
+  return <Text>Status: {alertState}</Text>;
+}
+```
+
+---
+
+## Available Hooks
+
+| Hook | Returns | Re-render Trigger |
+|---|---|---|
+| `useNavCoreContext()` | `{ engine: NavCore }` | Context mount |
+| `useNavSelector(selector, customEngine?, isEqual?)` | Selected slice `T` | When `isEqual(prev, next)` returns `false` |
+| `useNavInstruction(customEngine?)` | `NavInstruction \| null` | When upcoming turn text or geometryIndex changes |
+| `useNavAlert(customEngine?)` | `NavCoreState['alertState']` | On deviation or rejoin state transition |
+| `useNavProgress(customEngine?)` | `NavProgressInfo` | On progress index, arrival, or distance change |
+| `useNavIsOffRoute(customEngine?)` | `boolean` | When off-route flag changes |
+| `useNavSpeed(customEngine?)` | `number` (m/s) | On speed update |
+| `useNavCore(props)` | `UseNavCoreReturn` | Complete hook managing full engine lifecycle |
+
+---
+
+## Documentation
+
+- [React Native Integration Guide](../../docs/react-native.md)
+- [API Reference](../../docs/api-reference/navcore-react-native.md)
+- [Official Website](https://navcore-web.vercel.app/)
+
+---
+
+## Licensing
+
+Proprietary software. Copyright (c) 2026 Abdelnasser Aitabi. All rights reserved. No license is granted except by separate written agreement.

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;