@ingissa/navcore-react-native 1.0.3

package/dist/NavCoreProvider.d.ts

@@ -0,0 +1,33 @@
+/**
+ * NavCoreProvider — React Context for shared NavCore engine access.
+ *
+ * Use when multiple components need access to the same engine instance
+ * (e.g. map view, instruction banner, debug panel).
+ */
+import { type ReactNode } from 'react';
+import { NavCore, type NavCoreOptions } from '@ingissa/navcore-core';
+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>
+ * ```
+ */
+export declare function NavCoreProvider({ children, options }: NavCoreProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Access the shared NavCore engine from context.
+ * Must be used within a <NavCoreProvider>.
+ */
+export declare function useNavCoreContext(): NavCoreContextValue;
+export {};
+//# sourceMappingURL=NavCoreProvider.d.ts.map

package/dist/NavCoreProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavCoreProvider.d.ts","sourceRoot":"","sources":["../src/NavCoreProvider.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA8C,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACnF,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAErE,UAAU,mBAAmB;IAC3B,MAAM,EAAE,OAAO,CAAC;CACjB;AAID,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,oBAAoB,2CAe1E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,CAMvD"}

package/dist/NavCoreProvider.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * NavCoreProvider — React Context for shared NavCore engine access.
+ *
+ * Use when multiple components need access to the same engine instance
+ * (e.g. map view, instruction banner, debug panel).
+ */
+import { createContext, useContext, useRef, useMemo } from 'react';
+import { NavCore } from '@ingissa/navcore-core';
+const NavCoreContext = createContext(null);
+/**
+ * Wraps children with a shared NavCore engine instance.
+ *
+ * ```tsx
+ * <NavCoreProvider options={{ licenseKey: '...' }}>
+ *   <MapScreen />
+ *   <InstructionBanner />
+ * </NavCoreProvider>
+ * ```
+ */
+export function NavCoreProvider({ children, options }) {
+    const engineRef = useRef(null);
+    if (!engineRef.current) {
+        engineRef.current = new NavCore(options);
+    }
+    const value = useMemo(() => ({
+        engine: engineRef.current,
+    }), []);
+    return (_jsx(NavCoreContext.Provider, { value: value, children: children }));
+}
+/**
+ * Access the shared NavCore engine from context.
+ * Must be used within a <NavCoreProvider>.
+ */
+export function useNavCoreContext() {
+    const ctx = useContext(NavCoreContext);
+    if (!ctx) {
+        throw new Error('useNavCoreContext must be used within a <NavCoreProvider>');
+    }
+    return ctx;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @navcore/react-native — React Native bindings
+ *
+ * Provides hooks for integrating NavCore with React Native apps.
+ */
+export { useNavCore } from './useNavCore';
+export type { UseNavCoreProps, UseNavCoreReturn } from './useNavCore';
+export { NavCoreProvider, useNavCoreContext } from './NavCoreProvider';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @navcore/react-native — React Native bindings
+ *
+ * Provides hooks for integrating NavCore with React Native apps.
+ */
+export { useNavCore } from './useNavCore';
+export { NavCoreProvider, useNavCoreContext } from './NavCoreProvider';

package/dist/useNavCore.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+import { NavCore, type NavCoreOptions, type NavCoreState, type NavInstruction, type Coordinate } from '@ingissa/navcore-core';
+export 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?: React.MutableRefObject<{
+        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;
+}
+export interface UseNavCoreReturn extends NavCoreState {
+    /** The raw NavCore engine instance (for advanced usage) */
+    engine: NavCore;
+}
+export declare function useNavCore({ gpsCoord, gpsBearing, gpsAccuracy, gpsTimestamp, speed, routeGeometry, instructions, isNavigating, options, resumeAtIndex, outputRef, onDeviation, onRejoin, onInstruction, onArrival, pollRateHz, }: UseNavCoreProps): UseNavCoreReturn;
+//# sourceMappingURL=useNavCore.d.ts.map

package/dist/useNavCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNavCore.d.ts","sourceRoot":"","sources":["../src/useNavCore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAqB,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIjJ,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,aAAa,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACnC,8BAA8B;IAC9B,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,sDAAsD;IACtD,YAAY,EAAE,OAAO,CAAC;IACtB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,KAAK,CAAC,gBAAgB,CAAC;QACjC,KAAK,EAAE,UAAU,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,IAAI,CAAC,CAAC;IACV,yCAAyC;IACzC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,CAAC;IAC/E,mCAAmC;IACnC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACpD,0CAA0C;IAC1C,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,cAAc,KAAK,IAAI,CAAC;IACtD,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;CACjB;AAID,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,EACZ,KAAK,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,aAAa,EACb,SAAS,EACT,WAAW,EACX,QAAQ,EACR,aAAa,EACb,SAAS,EACT,UAAe,GAChB,EAAE,eAAe,GAAG,gBAAgB,CAwJpC"}

package/dist/useNavCore.js

@@ -0,0 +1,145 @@
+/**
+ * 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.
+ */
+import { useState, useEffect, useRef, useMemo } from 'react';
+import { NavCore } from '@ingissa/navcore-core';
+// ── Hook ──────────────────────────────────────────────────────
+export function useNavCore({ gpsCoord, gpsBearing, gpsAccuracy, gpsTimestamp, speed, routeGeometry, instructions, isNavigating, options, resumeAtIndex, outputRef, onDeviation, onRejoin, onInstruction, onArrival, pollRateHz = 30, }) {
+    // ── 1. Engine singleton ───────────────────────────────────────
+    const navRef = useRef(null);
+    if (!navRef.current) {
+        navRef.current = new NavCore(options);
+    }
+    const engine = navRef.current;
+    const [state, setState] = useState(() => engine.getState());
+    // ── 2. Event wiring ───────────────────────────────────────────
+    // 2a. Deviation
+    useEffect(() => {
+        if (!onDeviation)
+            return;
+        const handler = (data) => onDeviation(data);
+        engine.on('deviation', handler);
+        return () => { engine.off('deviation', handler); };
+    }, [engine, onDeviation]);
+    // 2b. Rejoin
+    useEffect(() => {
+        if (!onRejoin)
+            return;
+        const handler = (data) => onRejoin(data);
+        engine.on('rejoined', handler);
+        return () => { engine.off('rejoined', handler); };
+    }, [engine, onRejoin]);
+    // 2c. Instruction
+    useEffect(() => {
+        if (!onInstruction)
+            return;
+        const handler = (data) => onInstruction(data);
+        engine.on('instruction', handler);
+        return () => { engine.off('instruction', handler); };
+    }, [engine, onInstruction]);
+    // 2d. Arrival
+    useEffect(() => {
+        if (!onArrival)
+            return;
+        const handler = () => onArrival();
+        engine.on('arrival', handler);
+        return () => { engine.off('arrival', handler); };
+    }, [engine, onArrival]);
+    // ── 3. Route sync ────────────────────────────────────────────
+    useEffect(() => {
+        if (routeGeometry && routeGeometry.length >= 2) {
+            engine.setRoute(routeGeometry, instructions);
+        }
+    }, [engine, routeGeometry]);
+    // ── 4. Instructions sync (can change independently of route) ──
+    useEffect(() => {
+        if (instructions && instructions.length > 0 && routeGeometry && routeGeometry.length >= 2) {
+            engine.setRoute(routeGeometry, instructions);
+        }
+    }, [engine, instructions]);
+    // ── 5. GPS → engine pipeline ──────────────────────────────────
+    useEffect(() => {
+        if (!gpsCoord || !isNavigating)
+            return;
+        const gpsUpdate = {
+            coord: gpsCoord,
+            accuracy: gpsAccuracy ?? null,
+            bearing: gpsBearing ?? null,
+            speed,
+            timestamp: gpsTimestamp ?? Date.now(),
+        };
+        engine.update(gpsUpdate);
+    }, [engine, gpsCoord, gpsAccuracy, gpsBearing, gpsTimestamp, speed, isNavigating]);
+    // ── 6. Start navigation ───────────────────────────────────────
+    useEffect(() => {
+        if (isNavigating) {
+            engine.startNavigation();
+        }
+    }, [engine, isNavigating]);
+    // ── 7. Optimized state polling ────────────────────────────────
+    //    Polls at pollRateHz to batch state reads and minimize re-renders.
+    //    Only triggers setState when positional properties actually change.
+    useEffect(() => {
+        if (!isNavigating)
+            return;
+        const lastRef = {
+            snapped: [0, 0],
+            bearing: 0,
+            raw: [0, 0],
+        };
+        const intervalMs = Math.round(1000 / pollRateHz);
+        const poll = () => {
+            const live = engine.getState();
+            let changed = false;
+            // Bearing delta
+            if (Math.abs(live.bearing - lastRef.bearing) > 0.1) {
+                lastRef.bearing = live.bearing;
+                changed = true;
+            }
+            // Snapped coordinate delta
+            if (live.snappedCoord &&
+                (live.snappedCoord[0] !== lastRef.snapped[0] ||
+                    live.snappedCoord[1] !== lastRef.snapped[1])) {
+                lastRef.snapped = [live.snappedCoord[0], live.snappedCoord[1]];
+                changed = true;
+            }
+            // Raw GPS delta
+            if (live.rawGpsCoord &&
+                (live.rawGpsCoord[0] !== lastRef.raw[0] ||
+                    live.rawGpsCoord[1] !== lastRef.raw[1])) {
+                lastRef.raw = [live.rawGpsCoord[0], live.rawGpsCoord[1]];
+                changed = true;
+            }
+            if (changed) {
+                setState(live);
+            }
+            // Camera output ref
+            if (outputRef?.current !== undefined) {
+                outputRef.current = {
+                    coord: live.snappedCoord ?? lastRef.snapped,
+                    bearing: live.bearing,
+                    speed: live.currentSpeed,
+                };
+            }
+        };
+        const id = setInterval(poll, intervalMs);
+        return () => clearInterval(id);
+    }, [engine, isNavigating, pollRateHz, outputRef]);
+    // ── 8. Cleanup ────────────────────────────────────────────────
+    useEffect(() => {
+        return () => {
+            engine.destroy();
+            navRef.current = null;
+        };
+    }, [engine]);
+    // ── 9. Stable return ──────────────────────────────────────────
+    return useMemo(() => ({
+        ...state,
+        engine,
+    }), [state, engine]);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ingissa/navcore-react-native",
+  "version": "1.0.3",
+  "description": "React Native bindings for the NavCore navigation engine.",
+  "author": "Ingissa <8abnav@gmail.com>",
+  "license": "Commercial",
+  "homepage": "https://navcore-web.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ingissa/ingissa-navcore-examples.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ingissa/ingissa-navcore-examples/issues"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@ingissa/navcore-core": "^1.0.3",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "react-native-maps": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-maps": { "optional": true }
+  },
+  "dependencies": {}
+}