@mappedin/blue-dot 6.0.1-beta.56 → 6.0.1-beta.58

package/lib/esm/index.d.ts

@@ -1,19 +1,24 @@
 // Generated by dts-bundle v0.7.3
 // Dependencies for this module:
-//   ../blue-dot/@packages/internal/common/pubsub
 //   ../blue-dot/@mappedin/mappedin-js
-//   ../blue-dot/three
+//   ../blue-dot/@packages/internal/common/extensions
+//   ../blue-dot/@packages/internal/common/pubsub
 //   ../blue-dot/type-fest
+//   ../blue-dot/zod
+//   ../blue-dot/three
 
 declare module '@mappedin/blue-dot' {
     export { BlueDot } from '@mappedin/blue-dot/blue-dot/src/blue-dot';
-    export type { BlueDotEvents, BlueDotEventPayloads, BlueDotPositionUpdate, BlueDotState, BlueDotAction, FollowMode, FollowCameraOptions, BlueDotOptions, } from '@mappedin/blue-dot/blue-dot/src/types';
+    export type { BlueDotEvents, BlueDotEventPayloads, BlueDotPositionUpdate, BlueDotStatus, BlueDotAction, FollowMode, FollowCameraOptions, BlueDotState, BlueDotPositionProcessor, BlueDotPositionUpdateWithFloor, BlueDotUpdateOptions, GeolocationPositionExtended, } from '@mappedin/blue-dot/blue-dot/src/types';
 }
 
 declare module '@mappedin/blue-dot/blue-dot/src/blue-dot' {
+    import type { Floor, MapView, Model } from '@mappedin/mappedin-js';
+    import { Coordinate } from '@mappedin/mappedin-js';
+    import type { MapViewExtension } from '@packages/internal/common/extensions';
     import { PubSub } from '@packages/internal/common/pubsub';
-    import type { MapView } from '@mappedin/mappedin-js';
-    import type { BlueDotEventPayloads, BlueDotOptions, BlueDotPositionUpdate, BlueDotState, FollowCameraOptions, FollowMode } from '@mappedin/blue-dot/blue-dot/src/types';
+    import type { BlueDotEventPayloads, BlueDotState, BlueDotPositionProcessor, BlueDotPositionUpdate, BlueDotStatus, BlueDotUpdateOptions, FollowCameraOptions, FollowMode, GeolocationPositionExtended, BlueDotUpdateState } from '@mappedin/blue-dot/blue-dot/src/types';
+    import type { ReadonlyDeep } from 'type-fest';
     /**
         * Show a Blue Dot indicating the device's position on the map.
         *
@@ -37,45 +42,62 @@ declare module '@mappedin/blue-dot/blue-dot/src/blue-dot' {
         *
         * ```
         */
-    export class BlueDot {
+    export class BlueDot implements MapViewExtension<BlueDotState> {
             #private;
             /**
                 * Create a new {@link BlueDot} instance.
                 */
             constructor(mapView: MapView);
+            /**
+                * Get the Model for the BlueDot core element.
+                */
+            get dotModel(): Model | undefined;
+            /**
+                * Get the Model for the accuracy ring.
+                */
+            get accuracyRingModel(): Model | undefined;
+            /**
+                * Get the Model for the heading cone.
+                */
+            get headingConeModel(): Model | undefined;
+            /**
+                * Whether the BlueDot is currently enabled.
+                */
+            get isEnabled(): boolean;
             /**
                 * The current state of the BlueDot. Can be 'hidden', 'active', 'inactive', or 'disabled'.
-                * Listen for state changes using the 'state-change' event.
+                * Listen for state changes using the 'status-change' event.
                 *
                 * @example
-                * mapView.BlueDot.on('state-change', ({ state }) => {
-                *   if (state === 'active') {
+                * mapView.BlueDot.on('status-change', ({ status }) => {
+                *   if (status === 'active') {
                 *     // BlueDot is visible and tracking
                 *   }
                 * });
                 */
-            get state(): BlueDotState;
+            get status(): BlueDotStatus;
             /**
                 * Whether the BlueDot is currently following the user (camera follow mode).
                 */
-            get following(): boolean;
+            get isFollowing(): boolean;
             /**
                 * The direction the user is facing in degrees from north clockwise.
                 * @see https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates/heading
                 */
-            get heading(): number | null | undefined;
+            get heading(): GeolocationPosition['coords']['heading'] | undefined;
             /**
                 * The accuracy of the current position in metres.
                 */
-            get accuracy(): number | undefined;
+            get accuracy(): GeolocationPosition['coords']['accuracy'] | undefined;
             /**
                 * The coordinate of the current position.
                 */
-            get coordinate(): import("@mappedin/mappedin-js").Coordinate | undefined;
+            get coordinate(): Coordinate | undefined;
+            getState: () => ReadonlyDeep<BlueDotState>;
             /**
                 * The floor the Blue Dot is currently on. If undefined, the Blue Dot will appear on every floor.
                 */
-            get floor(): import("@mappedin/mappedin-js").Floor | undefined;
+            get floor(): Floor | undefined;
             /**
                 * Enable the Blue Dot. It will be hidden until a position is received either from the browser or by calling {@link BlueDot.update}.
                 * @param options - The options to setup the Blue Dot (see {@link BlueDotOptions}).
@@ -88,19 +110,41 @@ declare module '@mappedin/blue-dot/blue-dot/src/blue-dot' {
                 *
                 * @see See the [BlueDot Guide](https://developer.mappedin.com/web-sdk/blue-dot) for more information.
                 */
-            enable: (options?: BlueDotOptions) => void;
+            enable: (options?: BlueDotUpdateState) => void;
             /**
                 * Disable the Blue Dot. It will be hidden and no longer update.
                 */
             disable: () => void;
+            /**
+                * Subscribe to a BlueDot event.
+                * @param eventName The name of the event to listen for.
+                * @param fn The function to call when the event is emitted.
+                */
             on: PubSub<BlueDotEventPayloads>['on'];
+            /**
+                * Unsubscribe from a BlueDot event.
+                * @param eventName The name of the event to unsubscribe from.
+                * @param fn The function to unsubscribe from the event.
+                */
             off: PubSub<BlueDotEventPayloads>['off'];
+            /**
+                * Update the BlueDot state after it has been enabled.
+                * This allows overriding previously set values like colors, and other options.
+                * @param options - The options to update
+                *
+                * @example Update color and accuracy ring
+                * mapView.BlueDot.updateState({
+                *   color: '#ff0000',
+                *   accuracyRing: { color: '#ff0000', opacity: 0.5 }
+                * });
+                */
+            updateState: (options: BlueDotUpdateState) => void;
             /**
                 * Enable or disable the devices's geolocation listener to automatically position the Blue Dot.
                 * If enabled, the device will request permission to access the user's precise location.
                 * @param watch - Whether to enable or disable the listener.
                 */
-            watchDevicePosition: (watch?: boolean) => void;
+            watchDevicePosition: (watch: boolean) => void;
             /**
                 * Manually override some position properties of the Blue Dot.
                 * Accepts a full GeolocationPosition object or a partial {@link BlueDotPositionUpdate} object.
@@ -113,7 +157,7 @@ declare module '@mappedin/blue-dot/blue-dot/src/blue-dot' {
                 * api.BlueDot.update({ accuracy: 'device', heading: 'device' });
                 * ```
                 */
-            update: (position: BlueDotPositionUpdate) => void;
+            update: (position: GeolocationPositionExtended | BlueDotPositionUpdate | undefined, options?: BlueDotUpdateOptions) => void;
             /**
                 * Set the camera to follow the BlueDot in various modes. User interaction will cancel following automatically.
                 * @param mode The follow mode ('position-only', 'position-and-heading', 'position-and-path-direction', or false to disable).
@@ -123,13 +167,46 @@ declare module '@mappedin/blue-dot/blue-dot/src/blue-dot' {
                 * mapView.BlueDot.follow('position-and-heading', { zoomLevel: 21, pitch: 45 });
                 */
             follow: (mode: FollowMode, cameraOptions?: FollowCameraOptions) => void;
+            /**
+                * Set a position processor callback that allows intercepting and modifying device/geolocation position updates before they are applied.
+                *
+                * **Note**: This processor only applies to automatic position updates from device geolocation.
+                * Manual position updates via `update()` method bypass the processor and are applied directly.
+                *
+                * @param processor - A callback function that receives current state and incoming update. Return undefined to discard the update, or return a modified update object.
+                *
+                * @example Discard inaccurate positions
+                * ```ts
+                * blueDot.setPositionProcessor((current, incoming) => {
+                *   if (incoming.accuracy && incoming.accuracy > 50) {
+                *     return undefined; // Discard update
+                *   }
+                *   return incoming; // Accept update
+                * });
+                * ```
+                *
+                * @example Modify incoming positions
+                * ```ts
+                * blueDot.setPositionProcessor((current, incoming) => {
+                *   // Apply custom smoothing or validation logic
+                *   return {
+                *     ...incoming,
+                *     accuracy: Math.min(incoming.accuracy || 100, 10) // Cap accuracy
+                *   };
+                * });
+                * ```
+                */
+            setPositionProcessor(processor?: BlueDotPositionProcessor): void;
             destroy: () => void;
     }
 }
 
 declare module '@mappedin/blue-dot/blue-dot/src/types' {
     import type { Coordinate, Floor } from '@mappedin/mappedin-js';
+    import type z from 'zod';
     import type { EasingCurve } from '@mappedin/blue-dot/packages/common';
+    import type { positionSchema } from '@mappedin/blue-dot/blue-dot/src/schemas';
+    import type { PartialDeep } from 'type-fest';
     export type FollowMode = 
     /** Camera position follows the Blue Dot's position. */
     'position-only'
@@ -178,15 +255,15 @@ declare module '@mappedin/blue-dot/blue-dot/src/types' {
                     coordinate: Coordinate;
             };
             /**
-                * Emitted when the Blue Dot's state changes.
+                * Emitted when the Blue Dot's status changes.
                 */
-            'state-change': {
+            'status-change': {
                     /**
-                        * The new state of the Blue Dot.
+                        * The new status of the Blue Dot.
                         */
-                    state: BlueDotState;
+                    status: BlueDotStatus;
                     /**
-                        * The action that caused the state change.
+                        * The action that caused the status change.
                         */
                     action: BlueDotAction;
             };
@@ -216,79 +293,98 @@ declare module '@mappedin/blue-dot/blue-dot/src/types' {
             /**
                 * Emitted when the user hovers over the Blue Dot.
                 */
-            hover: undefined;
+            hover: {
+                    coordinate: Coordinate;
+            };
     };
     export type BlueDotEvents = keyof BlueDotEventPayloads;
-    export type BlueDotState = 'hidden' | 'active' | 'inactive' | 'disabled';
+    export type BlueDotStatus = 'hidden' | 'active' | 'inactive' | 'disabled';
     export type BlueDotAction = 'timeout' | 'error' | 'position-update' | 'enable' | 'disable' | 'initialize';
-    export type BlueDotOptions = {
+    export type BlueDotState = {
             /**
                 * The radius of the BlueDot in pixels. The BlueDot will maintain this size clamped to a minimum of 0.35 metres.
                 * @default 10
                 */
-            radius?: number;
+            radius: number;
             /**
                 * The color of the BlueDot core element.
                 * @default #2266ff
                 */
-            color?: string;
+            color: string;
             /**
                 * The color of the BlueDot when it has timed out and gone inactive.
                 * @default #808080
                 */
-            inactiveColor?: string;
+            inactiveColor: string;
             /**
                 * Options for the accuracy ring around the BlueDot.
                 */
-            accuracyRing?: {
+            accuracyRing: {
                     /**
                         * The color of the accuracy ring.
                         * @default #2266ff
                         */
-                    color?: string;
+                    color: string;
                     /**
                         * The opacity of the accuracy ring.
                         * @default 0.3
                         */
-                    opacity?: number;
+                    opacity: number;
             };
             /**
                 * Options for the heading directional indicator.
                 */
-            heading?: {
+            heading: {
                     /**
                         * The color of the heading cone.
                         * @default #2266ff
                         */
-                    color?: string;
+                    color: string;
                     /**
                         * The opacity of the heading cone.
                         * @default 0.7
                         */
-                    opacity?: number;
+                    opacity: number;
+                    /**
+                        * Whether to display the heading cone when the BlueDot is inactive (timed out).
+                        * @default false
+                        */
+                    displayWhenInactive: boolean;
             };
             /**
                 * The duration of the timeout in milliseconds.
                 * If the BlueDot does not receive a position update within this time, it will grey out until a position is received.
                 * @default 30000
                 */
-            timeout?: number;
+            timeout: number;
             /**
                 * Whether to watch the device's position.
                 * @default true
                 */
-            watchDevicePosition?: boolean;
+            watchDevicePosition: boolean;
             /**
                 * Whether to log debug messages.
                 * @default false
                 */
-            debug?: boolean;
+            debug: boolean;
             /**
                 * The maximum acceptable accuracy in meters. Position updates with accuracy exceeding this value will be dropped.
                 * @default 50
                 */
-            accuracyThreshold?: number;
+            accuracyThreshold: number;
+            /**
+                * The initial state of the BlueDot when enabled.
+                * @default 'hidden'
+                */
+            initialState: 'hidden' | 'inactive';
+            /**
+                * @hidden
+                * Whether the BlueDot must remain within the map bounds. Disabling this will disable analytics as well.
+                * @default true
+                */
+            preventOutOfBounds: boolean;
     };
+    export type BlueDotUpdateState = PartialDeep<BlueDotState>;
     /**
         * Position update options for the {@link BlueDot.update} method.
         */
@@ -321,6 +417,43 @@ declare module '@mappedin/blue-dot/blue-dot/src/types' {
                 * Set to `undefined` to disable floor level and show the BlueDot on all floors.
                 */
             floorOrFloorId?: Floor | string | 'device' | undefined;
+            /**
+                * Timestamp of the position update in milliseconds.
+                */
+            timestamp?: number;
+    };
+    export type BlueDotPositionUpdateWithFloor = Omit<BlueDotPositionUpdate, 'floorOrFloorId'> & {
+            floor?: Floor | 'device' | undefined;
+    };
+    export type ParsedBlueDotPosition = z.infer<typeof positionSchema>;
+    export type BlueDotPositionProcessor = (current: BlueDotPositionUpdateWithFloor, incoming: BlueDotPositionUpdateWithFloor) => BlueDotPositionUpdateWithFloor | undefined;
+    export type StateTransitions = {
+            [Action in BlueDotAction]?: BlueDotStatus;
+    };
+    export type StateMachine = {
+            [State in BlueDotStatus]: {
+                    actions: StateTransitions;
+            };
+    };
+    /**
+        * Options for the BlueDot update method.
+        */
+    export type BlueDotUpdateOptions = {
+            /**
+                * If true, maintains the current state and skips timers and analytics for this update.
+                * @default false
+                */
+            silent?: boolean;
+            /**
+                * If true, animates the position change. If false, updates immediately.
+                * @default true
+                */
+            animate?: boolean;
+    };
+    export type GeolocationPositionExtended = GeolocationPosition & {
+            coords: GeolocationPosition['coords'] & {
+                    readonly floorLevel?: number;
+            };
     };
 }
 
@@ -336,7 +469,31 @@ declare module '@mappedin/blue-dot/packages/common' {
     export { Logger };
     export * from '@mappedin/blue-dot/packages/common/color';
     export * from '@mappedin/blue-dot/packages/common/interpolate';
-    export * from '@mappedin/blue-dot/packages/common/type-utils';
+}
+
+declare module '@mappedin/blue-dot/blue-dot/src/schemas' {
+    import z from 'zod';
+    export const geolocationPositionSchema: z.ZodObject<{
+        coords: z.ZodObject<{
+            latitude: z.ZodNumber;
+            longitude: z.ZodNumber;
+            accuracy: z.ZodNumber;
+            altitude: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+            altitudeAccuracy: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+            heading: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+            speed: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+            floorLevel: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        }, z.core.$strip>;
+        timestamp: z.ZodNumber;
+    }, z.core.$strip>;
+    export const positionSchema: z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+        floor: z.ZodOptional<z.ZodAny>;
+        accuracy: z.ZodOptional<z.ZodNumber>;
+        heading: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        timestamp: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
 }
 
 declare module '@mappedin/blue-dot/packages/common/Mappedin.Logger' {
@@ -449,6 +606,30 @@ declare module '@mappedin/blue-dot/packages/common/utils' {
     export { clampWithWarning } from '@mappedin/blue-dot/packages/common/math-utils';
     export { arraysEqual } from '@mappedin/blue-dot/packages/common/array-utils';
     export function isBrowser(): boolean;
+    /**
+        * Calculates the simple Euclidean distance between two geographic coordinates.
+        *
+        * This treats longitude and latitude as Cartesian coordinates on a flat plane.
+        * It's the fastest distance calculation but least accurate for geographic data.
+        * Best used for relative distance comparisons rather than actual measurements.
+        *
+        * @param point1 - The first point's longitude and latitude as [longitude, latitude].
+        * @param point2 - The second point's longitude and latitude as [longitude, latitude].
+        * @returns The Euclidean distance between the two points in meters.
+        */
+    export function euclideanDistance(point1: Position, point2: Position): number;
+    /**
+        * Calculates the approximate distance between two geographic coordinates on Earth's surface.
+        *
+        * This function uses the equirectangular approximation method to compute the distance, which simplifies
+        * the math and speeds up calculations, but is less accurate over long distances compared to other methods
+        * like the haversine formula.
+        *
+        * @param point1 - The first point's longitude and latitude as [longitude, latitude].
+        * @param point2 - The second point's longitude and latitude as [longitude, latitude].
+        * @returns The approximate distance between the two points in meters.
+        */
+    export function equirectangularDistance(point1: Position, point2: Position): number;
 }
 
 declare module '@mappedin/blue-dot/packages/common/async' {
@@ -670,44 +851,6 @@ declare module '@mappedin/blue-dot/packages/common/interpolate' {
     export function interpolateMulti(value: number, inputRange: number[], outputRange: number[], easeFunc?: EasingCurve | ((t: number) => number)): number;
 }
 
-declare module '@mappedin/blue-dot/packages/common/type-utils' {
-    import type { SetOptional } from 'type-fest';
-    type Primitive = string | number | boolean | null | undefined;
-    export type PartialExcept<T, K extends string> = {
-            [P in keyof T as P extends K ? P : never]: T[P];
-    } & {
-            [P in keyof T as P extends K ? never : P]?: T[P] extends Primitive ? T[P] : T[P] extends (infer U)[] ? PartialExcept<U, K>[] : PartialExcept<T[P], K>;
-    };
-    /**
-        * Utility type that extracts nested values matching a specific type with recursion depth limit
-        * @example
-        * type A = ExtractDeep<{ a: { b: string; c: number; }; d: string; e: number; }, number>;
-        * // { a: { c: number; } e: number; }
-        */
-    export type ExtractDeep<T, U, Depth extends readonly number[] = []> = Depth['length'] extends 3 ? any : {
-            [K in keyof T as T[K] extends U ? K : T[K] extends object | undefined ? ExtractDeep<NonNullable<T[K]>, U, [...Depth, 0]> extends never ? never : K : never]: T[K] extends object | undefined ? undefined extends T[K] ? ExtractDeep<NonNullable<T[K]>, U, [...Depth, 0]> | undefined : ExtractDeep<NonNullable<T[K]>, U, [...Depth, 0]> : T[K] extends U ? T[K] : never;
-    };
-    /**
-        * Utility type that makes all properties of a type required, but allows undefined values
-        * to satisfy the required type.
-        * https://medium.com/terria/typescript-transforming-optional-properties-to-required-properties-that-may-be-undefined-7482cb4e1585
-        * @example
-        * type A = Complete<{ a: string; b: number; c: undefined; }>;
-        * // { a: string; b: number; c: undefined; }
-        */
-    export type Complete<T> = {
-            [P in keyof Required<T>]: Pick<T, P> extends Required<Pick<T, P>> ? T[P] : T[P] | undefined;
-    };
-    /**
-        * Utility type that makes all properties required except for the ones specified in the second argument.
-        * @example
-        * type A = RequiredExcept<{ a: string; b: number; c: undefined; }, 'c'>;
-        * // { a: string; b: number; c?: undefined; }
-        */
-    export type RequiredExcept<T, K extends keyof T> = SetOptional<Required<T>, K>;
-    export {};
-}
-
 declare module '@mappedin/blue-dot/packages/common/math-utils' {
     /**
       * Clamp a number between lower and upper bounds with a warning