@ingissa/navcore-react-native 1.0.7 → 1.0.9

package/src/NavCoreProvider.tsx

@@ -1,59 +0,0 @@
-/**
- * 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, type ReactNode } from 'react';
-import { NavCore, type NavCoreOptions } from '@ingissa/navcore-core';
-
-interface NavCoreContextValue {
-  engine: NavCore;
-}
-
-const NavCoreContext = createContext<NavCoreContextValue | null>(null);
-
-interface NavCoreProviderProps {
-  children: ReactNode;
-  options?: NavCoreOptions;
-}
-
-/**
- * Wraps children with a shared NavCore engine instance.
- *
- * ```tsx
- * <NavCoreProvider options={{ licenseKey: '...' }}>
- *   <MapScreen />
- *   <InstructionBanner />
- * </NavCoreProvider>
- * ```
- */
-export function NavCoreProvider({ children, options }: NavCoreProviderProps) {
-  const engineRef = useRef<NavCore | null>(null);
-  if (!engineRef.current) {
-    engineRef.current = new NavCore(options);
-  }
-
-  const value = useMemo(() => ({
-    engine: engineRef.current!,
-  }), []);
-
-  return (
-    <NavCoreContext.Provider value={value}>
-      {children}
-    </NavCoreContext.Provider>
-  );
-}
-
-/**
- * Access the shared NavCore engine from context.
- * Must be used within a <NavCoreProvider>.
- */
-export function useNavCoreContext(): NavCoreContextValue {
-  const ctx = useContext(NavCoreContext);
-  if (!ctx) {
-    throw new Error('useNavCoreContext must be used within a <NavCoreProvider>');
-  }
-  return ctx;
-}

package/src/index.ts

@@ -1,18 +0,0 @@
-/**
- * @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';
-export {
-  useNavSelector,
-  useNavInstruction,
-  useNavAlert,
-  useNavProgress,
-  useNavIsOffRoute,
-  useNavSpeed,
-  type NavProgressInfo,
-} from './useNavSelectors';

package/src/useNavCore.ts

@@ -1,208 +0,0 @@
-/**
- * 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, useCallback } from 'react';
-import {
-  NavCore,
-  type NavCoreOptions,
-  type NavGpsUpdate,
-  type NavCoreState,
-  type NavInstruction,
-  type Coordinate,
-} from '@ingissa/navcore-core';
-
-// ── Public types ──────────────────────────────────────────────
-
-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?: {
-    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;
-}
-
-export interface UseNavCoreReturn extends NavCoreState {
-  /** The raw NavCore engine instance (for advanced usage) */
-  engine: NavCore;
-}
-
-// ── Hook ──────────────────────────────────────────────────────
-
-export function useNavCore({
-  gpsCoord,
-  gpsBearing,
-  gpsAccuracy,
-  gpsTimestamp,
-  speed,
-  routeGeometry,
-  instructions,
-  isNavigating,
-  options,
-  resumeAtIndex,
-  outputRef,
-  onDeviation,
-  onRejoin,
-  onInstruction,
-  onArrival,
-  pollRateHz = 30,
-}: UseNavCoreProps): UseNavCoreReturn {
-
-  // ── 1. Engine singleton ───────────────────────────────────────
-  const navRef = useRef<NavCore | null>(null);
-  if (!navRef.current) {
-    navRef.current = new NavCore(options);
-  }
-  const engine = navRef.current;
-
-  const [state, setState] = useState<NavCoreState>(() => engine.getState());
-
-  // ── 2. Event wiring ───────────────────────────────────────────
-
-  // 2a. Deviation
-  useEffect(() => {
-    if (!onDeviation) return;
-    const handler = (data: unknown) => onDeviation(data as { anchorIndex: number; ghostCoord: Coordinate });
-    engine.on('deviation', handler);
-    return () => { engine.off('deviation', handler); };
-  }, [engine, onDeviation]);
-
-  // 2b. Rejoin
-  useEffect(() => {
-    if (!onRejoin) return;
-    const handler = (data: unknown) => onRejoin(data as { resumeIndex: number });
-    engine.on('rejoined', handler);
-    return () => { engine.off('rejoined', handler); };
-  }, [engine, onRejoin]);
-
-  // 2c. Instruction
-  useEffect(() => {
-    if (!onInstruction) return;
-    const handler = (data: unknown) => onInstruction(data as NavInstruction);
-    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: NavGpsUpdate = {
-      coord: gpsCoord,
-      accuracy: gpsAccuracy ?? null,
-      bearing: gpsBearing ?? null,
-      speed,
-      timestamp: gpsTimestamp ?? Date.now(),
-    };
-
-    const nextState = engine.update(gpsUpdate);
-
-    // Synchronous external camera/puck output with ZERO React re-renders
-    if (outputRef) {
-      outputRef.current = {
-        coord: nextState.snappedCoord ?? gpsCoord,
-        bearing: nextState.bearing,
-        speed: nextState.currentSpeed,
-      };
-    }
-  }, [engine, gpsCoord, gpsAccuracy, gpsBearing, gpsTimestamp, speed, isNavigating, outputRef]);
-
-  // ── 6. Start navigation ───────────────────────────────────────
-  useEffect(() => {
-    if (isNavigating) {
-      engine.startNavigation();
-    }
-  }, [engine, isNavigating]);
-
-  // ── 7. Push-based reactive state subscription ─────────────────
-  //    Eliminates the 30 Hz setInterval loop. Updates state reactively
-  //    only when new engine state is computed.
-  useEffect(() => {
-    if (!isNavigating) return;
-
-    const handleUpdate = (updatedState: unknown) => {
-      setState(updatedState as NavCoreState);
-    };
-
-    engine.on('update', handleUpdate);
-    setState(engine.getState());
-
-    return () => {
-      engine.off('update', handleUpdate);
-    };
-  }, [engine, isNavigating]);
-
-  // ── 8. Cleanup ────────────────────────────────────────────────
-  useEffect(() => {
-    return () => {
-      engine.destroy();
-      navRef.current = null;
-    };
-  }, [engine]);
-
-  // ── 9. Stable return ──────────────────────────────────────────
-  return useMemo(() => ({
-    ...state,
-    engine,
-  }), [state, engine]);
-}

package/src/useNavSelectors.ts

@@ -1,143 +0,0 @@
-/**
- * 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.
- */
-
-import { useSyncExternalStore, useRef, useCallback } from 'react';
-import type { NavCore, NavCoreState, NavInstruction } from '@ingissa/navcore-core';
-import { useNavCoreContext } from './NavCoreProvider';
-
-/**
- * Generic reactive selector subscribing to NavCore state updates.
- * Only triggers re-renders when the selected value actually changes.
- */
-export function useNavSelector<T>(
-  selector: (state: NavCoreState) => T,
-  customEngine?: NavCore,
-  isEqual: (a: T, b: T) => boolean = Object.is
-): T {
-  let contextEngine: NavCore | undefined;
-  try {
-    contextEngine = useNavCoreContext().engine;
-  } catch {
-    contextEngine = undefined;
-  }
-
-  const engine = customEngine ?? contextEngine;
-  if (!engine) {
-    throw new Error('useNavSelector must be provided an engine or used within a NavCoreProvider');
-  }
-
-  const lastSelectedRef = useRef<T | undefined>(undefined);
-  const lastStateRef = useRef<NavCoreState | undefined>(undefined);
-
-  const getSnapshot = useCallback(() => {
-    const currentState = engine.getState();
-    if (lastStateRef.current === currentState && lastSelectedRef.current !== undefined) {
-      return lastSelectedRef.current;
-    }
-    const nextSelected = selector(currentState);
-    if (lastSelectedRef.current !== undefined && isEqual(lastSelectedRef.current, nextSelected)) {
-      return lastSelectedRef.current;
-    }
-    lastStateRef.current = currentState;
-    lastSelectedRef.current = nextSelected;
-    return nextSelected;
-  }, [engine, selector, isEqual]);
-
-  const subscribe = useCallback((onStoreChange: () => void) => {
-    engine.on('update', onStoreChange);
-    return () => {
-      engine.off('update', onStoreChange);
-    };
-  }, [engine]);
-
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-}
-
-/**
- * Hook to select the current upcoming turn-by-turn navigation instruction.
- * Only re-renders when the instruction changes or triggers.
- */
-export function useNavInstruction(customEngine?: NavCore): NavInstruction | null {
-  return useNavSelector(
-    (state) => {
-      if (state.nextInstructionIndex === null) return null;
-      let engine = customEngine;
-      if (!engine) {
-        try { engine = useNavCoreContext().engine; } catch { /* ignore */ }
-      }
-      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)
-  );
-}
-
-/**
- * Hook to select current alert/deviation state ('NONE' | 'DEVIATING' | 'RECALCULATING' | 'REJOINING' | 'REJOINED').
- * Only re-renders on alert state transitions.
- */
-export function useNavAlert(customEngine?: NavCore): NavCoreState['alertState'] {
-  return useNavSelector(
-    (state) => state.alertState,
-    customEngine,
-    Object.is
-  );
-}
-
-export interface NavProgressInfo {
-  distanceToDestination: number | null;
-  distanceToNextInstruction: number | null;
-  progressIndex: number;
-  routeIndex: number;
-  hasArrived: boolean;
-}
-
-/**
- * Hook to select navigation progress and remaining distance metrics.
- */
-export function useNavProgress(customEngine?: NavCore): NavProgressInfo {
-  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
-  );
-}
-
-/**
- * Hook to select whether the vehicle is currently off-route.
- */
-export function useNavIsOffRoute(customEngine?: NavCore): boolean {
-  return useNavSelector(
-    (state) => state.isOffRoute,
-    customEngine,
-    Object.is
-  );
-}
-
-/**
- * Hook to select current speed in m/s.
- */
-export function useNavSpeed(customEngine?: NavCore): number {
-  return useNavSelector(
-    (state) => state.currentSpeed,
-    customEngine,
-    Object.is
-  );
-}