React Hooks Reference

BloomSpark 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
}

---

📊 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;
}

---

✏️ 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>;
};