React Hooks Reference

DigiNest uses a set of clean, fully typed React hooks to let components interact with map context, floor levels, cameras, real-time tracking, drawing tools, and custom data streams.

---

🧭 useSpatialMap

Accesses the raw MapLibre GL JS instance and loading states. Must be consumed inside a child component of <SpatialMap>.

function useSpatialMap(): {
  /** The raw MapLibre Map instance (null until loaded). */
  map: maplibregl.Map | null;
  /** True when map style assets and core components have rendered. */
  isLoaded: boolean;
};

---

🏢 useFloor

Controls floor-switching states, ordinal queries, and custom multi-level visibility configurations.

function useFloor(buildingId: string): {
  /** Current active Level configuration. */
  current: Level | undefined;
  
  /** Switch active floor by ordinal integer (e.g. 1, 2, -1). */
  setCurrentByOrdinal: (ordinal: number) => void;
  
  /** Render multiple floors up to level N (translucent stacking overlays). */
  showUpToOrdinal: (ordinal: number) => void;
  
  /** Resets multi-floor stacked views back to single-floor isolation mode. */
  resetVisibility: () => void;
  
  /** Array of level configurations available in the building. */
  levels: Level[];
};

interface Level {
  id: string;
  ordinal: number;
  name: Record<string, string>;
  short_name: Record<string, string>;
}

---

🎥 useCamera

Controls smooth camera flyTo, fitBounds, oblique 3D pivots, and coordinate focus animations.

function useCamera(): {
  /** Retrieves a serializable snapshot of the active viewport. */
  getCameraPlacement(): CameraPlacement;
  
  /** Overwrites viewport coordinates instantly. */
  setCameraPlacement(p: CameraPlacement): void;
  
  /** Triggers a smooth ease fly animation to coordinates. */
  animateTo(p: CameraPlacement, opts?: { duration?: number }): Promise<void>;
  
  /** Centers on bounding boxes or specific GeoJSON features. */
  focusOn(target: BoundingBox | string | [number, number], opts?: { padding?: number }): Promise<void>;
  
  /** Zoom and pivot to center a complete building footprint. */
  fitBuilding(buildingId: string): Promise<void>;
  
  /** Zoom and center a specific floor plan footprint. */
  fitFloor(floorId: string): Promise<void>;
};

interface CameraPlacement {
  longitude: number;
  latitude: number;
  zoom: number;
  pitch: number;
  bearing: number;
  alpha?: number;  // Smplrspace legacy orbital azimuth
  beta?: number;   // Smplrspace legacy orbital elevation
  radius?: number; // Smplrspace legacy zoom radius
}

---

🗺️ useCameraSlice (v2.16)

Exposes low-level camera state including the new zoomMode and venueBounds values from cameraSlice.

function useCameraSlice(): {
  /** Current zoom-context: 'overview' (zoom < 18) or 'indoor' (zoom ≥ 18). */
  zoomMode: ZoomMode;

  /** Active venue bounding box constraint, or null if unset. */
  venueBounds: VenueBounds | null;

  /** Set or clear the camera bounding constraint. Wires to map.setMaxBounds(). */
  setVenueBounds: (bounds: VenueBounds | null) => void;
};

type ZoomMode = 'overview' | 'indoor';
type VenueBounds = [[number, number], [number, number]];

---

📊 useDataLayer

Programmatically creates, registers, modifies, or toggles custom developer layers on the active map.

function useDataLayer<T extends DataLayerSpec>(spec: T): DataLayerController<T>;

interface DataLayerController<T> {
  /** Modify specific layer parameters or dataset coordinates on the fly. */
  update: (next: Partial<T>) => void;
  
  /** Completely unregisters and destroys the layer. */
  remove: () => void;
  
  /** Render the layer visible. */
  show: () => void;
  
  /** Temporarily hide the layer. */
  hide: () => void;
}

---

📡 useRTLS

Establishes bindings to live RTLS position streams. Leverages Web Workers to run smoothing and coordinate transformations in background threads.

function useRTLS(
  adapter: RTLSAdapter, 
  opts?: {
    /** Kalman smoothing filter settings. Default is 'kalman'. */
    smoothing?: 'kalman' | 'none';
    /** Auto-expire assets off the map if no updates in N milliseconds. Default is 30,000. */
    deadReckoningMs?: number;
    /** Triggered on every raw incoming position packet. */
    onPosition?: (u: PositionUpdate) => void;
  }
): { 
  /** A fast reference-based map containing current asset locations. */
  positions: Map<string, PositionUpdate>; 
  /** Connection states, reconnection retries, and timing offsets. */
  health: AdapterHealth; 
};

interface PositionUpdate {
  assetId: string;
  buildingId?: string;
  floorId?: string;
  x?: number; y?: number; z?: number; // meter mode
  longitude?: number; latitude?: number; // latlon mode
  accuracy?: number;
  ts: number;
}

---

🖱️ useFeatureClick (v2.16, #378)

Subscribes to map click events on the specified layer IDs and returns the clicked feature.

import { useFeatureClick } from '@diginestai/ui';

function Overlay({ map }) {
  const { feature, lngLat, close } = useFeatureClick(map, ['floor-fill']);

  if (!feature) return null;
  return <FeaturePopup feature={feature} lngLat={lngLat} onClose={close} />;
}

function useFeatureClick(
  map: maplibregl.Map | null,
  layerIds: string[]
): {
  /** The last clicked feature, or null if no feature is selected. */
  feature: maplibregl.MapGeoJSONFeature | null;
  /** LngLat of the click that produced the current feature. */
  lngLat: maplibregl.LngLat | null;
  /** Clears the current selection. */
  close: () => void;
};

---

🔍 useIndoorSearch (v2.16, #379)

Client-side fuzzy search over a GeoJSON feature pool. Returns filtered results synchronously on each keystroke.

import { useIndoorSearch } from '@diginestai/ui';

const { query, setQuery, results } = useIndoorSearch(features, ['name', 'category']);

function useIndoorSearch(
  features: GeoJSON.Feature[],
  searchKeys?: string[]
): {
  /** Current search query string. */
  query: string;
  /** Update the search query. */
  setQuery: (q: string) => void;
  /** Features matching the current query. Empty array when query is empty. */
  results: GeoJSON.Feature[];
};

---

🧭 useWayfinding (v2.16, #380)

Manages draggable start/stop coordinates and triggers A* path recalculation.

import { useWayfinding } from '@diginestai/ui';

const { setStart, setStop, path, reset } = useWayfinding(graph, blockedUnitIds);

function useWayfinding(
  graph: WayfindingGraph,
  obstacles?: string[]
): {
  /** Set start coordinate [lng, lat]. Triggers route recalculation. */
  setStart: (coord: [number, number]) => void;
  /** Set stop coordinate [lng, lat]. Triggers route recalculation. */
  setStop: (coord: [number, number]) => void;
  /** Computed route, or null if route cannot be found. */
  path: NavigationPath | null;
  /** Current start coordinate, or null if not set. */
  startCoord: [number, number] | null;
  /** Current stop coordinate, or null if not set. */
  stopCoord: [number, number] | null;
  /** Clears start, stop, and path. */
  reset: () => void;
};

---

✏️ useEditor

Retrieves state bindings and transactional operations for the built-in geometry digital twin drawing tools.

function useEditor(): {
  /** The current active editing tool mode. */
  mode: EditorMode;
  
  /** Change active drawing state. */
  setMode: (m: EditorMode) => void;
  
  /** Set containing selected feature UUIDs. */
  selection: Set<string>;
  
  /** Triggers the multi-floor spatial offset copy algorithm. */
  copyToFloor: (ids: string[], targetLevelId: string, opts?: CopyOptions) => void;
  
  /** Triggers the cross-building georeferenced copy algorithm. */
  copyToBuilding: (ids: string[], targetBuildingId: string, opts?: CopyOptions) => void;
  
  /** Step backward in the temporal patch state stack. */
  undo: () => void;
  
  /** Step forward in the temporal patch state stack. */
  redo: () => void;
  
  /** Export geometries as a zipped IMDF package. */
  exportIMDF: (profile: 'apple' | 'microsoft') => Promise<Blob>;
};