@mappedin/blue-dot 6.14.0-beta.0 → 6.16.0-beta.0

package/README.md

@@ -33,20 +33,26 @@ blueDot.enable();
 // Listening to device position updates from the browser
 blueDot.watchDevicePosition(true);
 
-// Send custom position updates from a different source
-blueDot.update({
-  // Latitude of the update
-  latitude,
-  // Longitude of the update
-  longitude,
-  // Optional accuracy in meters
-  accuracy,
-  // Optional heading in degrees from north
-  heading,
-  // Optional floor or floor ID
-  floorOrFloorId,
+// Report a position from an external source (e.g., custom IPS)
+blueDot.reportPosition({
+  latitude: 43.6532,
+  longitude: -79.3832,
+  confidence: 0.8, // 0-1 confidence score
+  heading: 90, // Optional heading in degrees
+  floorLevel: 0, // Optional floor level
 });
 
+// Force position to a known location (overrides all other sources)
+blueDot.forcePosition(
+  {
+    latitude: 43.6532,
+    longitude: -79.3832,
+    heading: 90,
+    floorLevel: 0,
+  },
+  30000, // How long to hold this position in ms
+);
+
 // Attach the camera to the BlueDot
 blueDot.follow('position-only');
 ```
@@ -59,7 +65,7 @@ blueDot.follow('position-only');
 
 ```ts
 // Browser will prompt for permission
-await blueDot.watchDevicePosition(true);
+blueDot.watchDevicePosition(true);
 
 // Listen for errors (including permission denied)
 blueDot.on('error', error => {
@@ -115,7 +121,24 @@ Disable and hide the BlueDot. Stops all position tracking.
 blueDot.disable();
 ```
 
-#### `watchDevicePosition(watch: boolean): Promise<void>`
+#### `getState(): ReadonlyDeep<BlueDotState>`
+
+Returns the current BlueDot configuration (radius, colors, timeout, etc.).
+
+```ts
+const state = blueDot.getState();
+console.log(state.radius, state.color);
+```
+
+#### `updateState(options: BlueDotUpdateState): void`
+
+Update BlueDot options after it has been enabled (e.g. colors, timeout, accuracy threshold).
+
+```ts
+blueDot.updateState({ color: '#ff0000', timeout: 60000 });
+```
+
+#### `watchDevicePosition(watch: boolean): void`
 
 Start or stop listening to device GPS position.
 
@@ -124,8 +147,8 @@ Start or stop listening to device GPS position.
 - Emits `error` events on geolocation errors
 
 ```ts
-await blueDot.watchDevicePosition(true); // Start tracking
-await blueDot.watchDevicePosition(false); // Stop tracking
+blueDot.watchDevicePosition(true); // Start tracking
+blueDot.watchDevicePosition(false); // Stop tracking
 ```
 
 #### `watchDeviceOrientation(watch: boolean): Promise<void>`
@@ -143,9 +166,61 @@ button.addEventListener('click', async () => {
 });
 ```
 
-#### `update(position, options?)`
+#### `reportPosition(options)`
+
+Report a position from an external source (e.g., custom Indoor Positioning System). The position is fed into the fusion engine with a confidence score that influences how much weight it receives relative to other sources like GPS.
+
+```ts
+blueDot.reportPosition({
+	latitude: 43.6532,
+	longitude: -79.3832,
+	confidence: 0.8, // 0-1: higher = more influence on fused position
+	heading: 90, // Optional: degrees from north
+	floorLevel: 0, // Optional: floor level
+});
+```
+
+Parameters:
+
+- `latitude: number` - Latitude coordinate (required)
+- `longitude: number` - Longitude coordinate (required)
+- `confidence?: number` - Confidence score from 0 to 1 (default: 0.5)
+- `accuracy?: number` - Accuracy in meters
+- `heading?: number` - Heading in degrees from north
+- `floorLevel?: number` - Floor level
+- `timestamp?: number` - Timestamp in milliseconds (default: Date.now())
+
+#### `forcePosition(position, durationMs?)`
+
+Force the BlueDot to a specific position, overriding all other data sources for a specified duration. Use this when you have an authoritative position from a calibration source like Visual Positioning (VPS) or AI Localizer.
+
+```ts
+blueDot.forcePosition(
+	{
+		latitude: 43.6532,
+		longitude: -79.3832,
+		heading: 90, // Optional: degrees from north
+		floorLevel: 0, // Optional: floor level
+	},
+	30000, // How long to hold (default: 30 seconds)
+);
+```
+
+Parameters:
 
-Manually set or override position properties.
+- `position.latitude: number` - Latitude coordinate (required)
+- `position.longitude: number` - Longitude coordinate (required)
+- `position.heading?: number` - Heading in degrees from north
+- `position.floorLevel?: number` - Floor level
+- `durationMs?: number` - Duration in milliseconds (default: 30000)
+
+During the forced period, GPS and other position sources are ignored. After expiration, the BlueDot transitions back to using fused position data. Emits `anchor-set` when activated and `anchor-expired` when the duration ends.
+
+#### `update(position, options?)` _(deprecated)_
+
+> **Deprecated**: Use `reportPosition()` for feeding positions into the fusion engine, or `forcePosition()` to set an authoritative position anchor.
+
+Legacy method to manually set or override position properties.
 
 ```ts
 // Set full position
@@ -184,11 +259,13 @@ blueDot.follow('position-and-path-direction');
 blueDot.follow(false);
 ```
 
-Camera options:
+Camera options (`FollowCameraOptions`):
 
-- `zoomLevel?: number` - Target zoom level
-- `pitch?: number` - Camera pitch angle
-- `animationDuration?: number` - Animation duration in ms
+- `zoomLevel?: number` - Target zoom level (default: 21)
+- `pitch?: number` - Camera pitch angle (default: 45)
+- `bearing?: number` - Camera bearing in degrees (position-only mode only)
+- `duration?: number` - Animation duration in ms (default: 1000)
+- `easing?: 'ease-in' | 'ease-out' | 'ease-in-out' | 'linear'` - Animation easing (default: 'ease-in-out')
 
 #### `setPositionProcessor(processor?)`
 
@@ -272,8 +349,8 @@ Fired when BlueDot status changes.
 
 ```ts
 blueDot.on('status-change', event => {
-	console.log(event.status); // New status
-	console.log(event.previousStatus); // Previous status
+	console.log(event.status); // New status: 'hidden' | 'active' | 'inactive' | 'disabled'
+	console.log(event.action); // Action that caused the change: 'timeout' | 'error' | 'position-update' | 'enable' | 'disable' | 'initialize'
 });
 ```
 
@@ -303,7 +380,8 @@ Fired when follow mode changes.
 
 ```ts
 blueDot.on('follow-change', event => {
-	console.log(event.mode); // Current follow mode or false
+	console.log(event.following); // Whether the camera is following the BlueDot
+	console.log(event.mode); // Follow mode when following: 'position-only' | 'position-and-heading' | 'position-and-path-direction'
 });
 ```
 
@@ -327,10 +405,59 @@ blueDot.on('hover', event => {
 });
 ```
 
+### `anchor-set`
+
+Fired when a position anchor is set via `forcePosition()` or a custom sensor.
+
+```ts
+blueDot.on('anchor-set', event => {
+	console.log('Anchor set:', event.anchor);
+	console.log('Position:', event.anchor.latitude, event.anchor.longitude);
+	console.log('From sensor:', event.anchor.sensorId);
+});
+```
+
+### `anchor-expired`
+
+Fired when a position anchor expires after its duration.
+
+```ts
+blueDot.on('anchor-expired', event => {
+	console.log('Anchor expired:', event.anchor.sensorId);
+	// BlueDot will now use fused position data again
+});
+```
+
+## Options
+
+```ts
+blueDot.on('anchor-set', event => {
+	console.log('Anchor set:', event.anchor);
+	console.log('Position:', event.anchor.latitude, event.anchor.longitude);
+	console.log('From sensor:', event.anchor.sensorId);
+});
+```
+
+### `anchor-expired`
+
+Fired when a position anchor expires after its duration.
+
+```ts
+blueDot.on('anchor-expired', event => {
+	console.log('Anchor expired:', event.anchor.sensorId);
+	// BlueDot will now use fused position data again
+});
+```
+
 ## Options
 
+Options for `enable()` and `updateState()`. All properties are optional. The type is exported as `BlueDotUpdateState` from `@mappedin/blue-dot`.
+
 ```ts
-export type BlueDotOptions = {
+import type { BlueDotUpdateState } from '@mappedin/blue-dot';
+
+// BlueDotUpdateState structure (all properties optional)
+interface Options {
 	/**
 	 * The radius of the BlueDot in pixels. The BlueDot will maintain this size clamped to a minimum of 0.35 metres.
 	 * @default 10
@@ -399,12 +526,12 @@ export type BlueDotOptions = {
 	initialState?: 'hidden' | 'inactive';
 	/**
 	 * Whether to prevent position updates outside the map bounds.
-	 * @default false
+	 * @default true
 	 */
 	preventOutOfBounds?: boolean;
 	/**
-	 * Maximum accuracy (in meters) to accept. Updates with lower accuracy are ignored.
-	 * @default Infinity
+	 * Maximum accuracy (in meters) to accept. Updates exceeding this value are dropped.
+	 * @default 50
 	 */
 	accuracyThreshold?: number;
 	/**
@@ -412,9 +539,114 @@ export type BlueDotOptions = {
 	 * @default false
 	 */
 	debug?: boolean;
-};
+}
+```
+
+## Custom Sensors
+
+You can create custom sensors to provide position data from your own sources (e.g., BLE beacons, Wi-Fi triangulation, visual positioning). Custom sensors extend `BaseSensor` and can publish position updates or set authoritative position anchors.
+
+### Creating a Custom Sensor
+
+```ts
+import { BaseSensor } from '@mappedin/blue-dot';
+
+class MyPositioningSensor extends BaseSensor {
+	readonly id = 'my-ips';
+	readonly requiresPermission = false;
+
+	protected async start(): Promise<void> {
+		// Start your positioning system
+		this.myIps.onPosition((lat, lng, confidence) => {
+			// Publish absolute position updates via the internal event system
+			this.publish('absolute-update', {
+				sensorId: this.id,
+				update: {
+					latitude: lat,
+					longitude: lng,
+					confidence, // 0-1
+					timestamp: Date.now(),
+				},
+			});
+		});
+	}
+
+	protected stop(): void {
+		// Clean up your positioning system
+		this.myIps.stop();
+	}
+
+	async checkPermission(): Promise<'granted' | 'denied' | 'prompt' | 'unavailable'> {
+		return 'granted';
+	}
+
+	async requestPermission(): Promise<'granted' | 'denied' | 'prompt' | 'unavailable'> {
+		return 'granted';
+	}
+}
+```
+
+### Setting Position Anchors from Custom Sensors
+
+Custom sensors can set authoritative position anchors using `this.setAnchor()`. This is useful for calibration sources like Visual Positioning (VPS) or AI localization.
+
+```ts
+class MyLocalizerSensor extends BaseSensor {
+	readonly id = 'my-localizer';
+	readonly requiresPermission = false;
+
+	async localize(imageData: Blob): Promise<void> {
+		const result = await this.callLocalizerApi(imageData);
+
+		// Set an anchor - this overrides other position sources
+		this.setAnchor({
+			latitude: result.latitude,
+			longitude: result.longitude,
+			heading: result.bearing,
+			floorLevel: result.floor,
+			ttl: 60000, // Anchor valid for 60 seconds
+			confidence: 0.95, // High confidence
+			anchorOnlyPeriodMs: 5000, // Ignore GPS for first 5 seconds
+		});
+	}
+
+	clearLocalization(): void {
+		this.clearAnchor();
+	}
+
+	// ... other required methods
+}
+```
+
+### Registering Custom Sensors
+
+```ts
+const blueDot = new BlueDot(mapView);
+
+// Create and register your sensor
+const mySensor = new MyPositioningSensor();
+blueDot.Sensors.register(mySensor);
+
+// Enable the sensor
+mySensor.enable();
+
+// Access built-in sensors via .get()
+blueDot.Sensors.get('geolocation').enable();
+blueDot.Sensors.get('deviceorientation').enable();
 ```
 
+### Anchor Options
+
+When calling `setAnchor()`, you can configure:
+
+- `latitude: number` - Latitude coordinate (required)
+- `longitude: number` - Longitude coordinate (required)
+- `heading?: number` - Heading in degrees from north
+- `floorLevel?: number` - Floor level
+- `ttl?: number` - Time-to-live in milliseconds (default: 30000)
+- `confidence?: number` - Confidence score 0-1 (default: 1.0)
+- `anchorOnlyPeriodMs?: number` - Duration to ignore other sources (default: 5000)
+
 ## React Native
 
 ```tsx
@@ -442,15 +674,17 @@ function BlueDotDisplay() {
 	const {
 		isReady,
 		isEnabled,
-		state,
-		position,
+		status,
+		coordinate,
 		floor,
 		isFollowing,
 		accuracy,
 		heading,
 		enable,
 		disable,
-		update,
+		update, // Deprecated: use reportPosition or forcePosition
+		reportPosition,
+		forcePosition,
 		follow,
 	} = useBlueDot();
 
@@ -462,11 +696,11 @@ function BlueDotDisplay() {
 		}, []),
 	);
 
-	// Listen for state changes
+	// Listen for status changes
 	useBlueDotEvent(
-		'state-change',
+		'status-change',
 		useCallback(event => {
-			console.log('State changed:', event.state);
+			console.log('Status changed:', event.status);
 		}, []),
 	);
 
@@ -478,6 +712,21 @@ function BlueDotDisplay() {
 		}, []),
 	);
 
+	// Listen for anchor events (from forcePosition or custom sensors)
+	useBlueDotEvent(
+		'anchor-set',
+		useCallback(event => {
+			console.log('Anchor set from:', event.anchor.sensorId);
+		}, []),
+	);
+
+	useBlueDotEvent(
+		'anchor-expired',
+		useCallback(event => {
+			console.log('Anchor expired:', event.anchor.sensorId);
+		}, []),
+	);
+
 	useEffect(() => {
 		if (isReady && !isEnabled) {
 			// All methods are async - use await or .then()
@@ -489,15 +738,14 @@ function BlueDotDisplay() {
 		}
 	}, [isReady, isEnabled, enable]);
 
-	const handleUpdatePosition = useCallback(async () => {
+	const handleReportPosition = useCallback(async () => {
 		try {
-			// Update position manually
-			await update({
+			// Report position from external IPS
+			await reportPosition({
 				latitude: 43.6532,
 				longitude: -79.3832,
-				accuracy: 5,
+				confidence: 0.8,
 				heading: 90,
-				floorOrFloorId: floor,
 			});
 
 			// Enable follow mode
@@ -505,25 +753,45 @@ function BlueDotDisplay() {
 				zoomLevel: 19,
 			});
 		} catch (error) {
-			console.error('Failed to update position:', error);
+			console.error('Failed to report position:', error);
 		}
-	}, [update, follow, floor]);
+	}, [reportPosition, follow]);
+
+	const handleForcePosition = useCallback(async () => {
+		try {
+			// Force position from calibration source
+			await forcePosition(
+				{
+					latitude: 43.6532,
+					longitude: -79.3832,
+					heading: 90,
+					floorLevel: 0,
+				},
+				30000,
+			);
+		} catch (error) {
+			console.error('Failed to force position:', error);
+		}
+	}, [forcePosition]);
 
 	return (
 		<View>
 			<Text>Is Ready: {isReady ? 'Yes' : 'No'}</Text>
 			<Text>Is Enabled: {isEnabled ? 'Yes' : 'No'}</Text>
-			<Text>State: {state}</Text>
+			<Text>Status: {status}</Text>
 			<Text>Following: {isFollowing ? 'Yes' : 'No'}</Text>
-			{position && (
+			{coordinate && (
 				<Text>
-					Position: {position.latitude.toFixed(4)}, {position.longitude.toFixed(4)}
+					Position: {coordinate.latitude.toFixed(4)}, {coordinate.longitude.toFixed(4)}
 				</Text>
 			)}
 			{accuracy && <Text>Accuracy: {accuracy.toFixed(1)}m</Text>}
 			{heading && <Text>Heading: {heading.toFixed(0)}°</Text>}
-			<TouchableOpacity onPress={handleUpdatePosition}>
-				<Text>Update Position & Follow</Text>
+			<TouchableOpacity onPress={handleReportPosition}>
+				<Text>Report Position & Follow</Text>
+			</TouchableOpacity>
+			<TouchableOpacity onPress={handleForcePosition}>
+				<Text>Force Position (Calibration)</Text>
 			</TouchableOpacity>
 		</View>
 	);
@@ -532,6 +800,6 @@ function BlueDotDisplay() {
 
 **Key Differences from Vanilla JS:**
 
-- **All methods are async**: `enable()`, `disable()`, `update()`, and `follow()` return Promises
+- **All methods are async**: `enable()`, `disable()`, `reportPosition()`, `forcePosition()`, and `follow()` return Promises
 - **Rich state**: Hook returns `isReady`, `state`, `position`, `floor`, `isFollowing`, `accuracy`, `heading` for real-time updates
-- **Separate event hook**: Use `useBlueDotEvent` for listening to position-update, state-change, and follow-change events
+- **Separate event hook**: Use `useBlueDotEvent` for listening to position-update, state-change, follow-change, anchor-set, and anchor-expired events