@mappedin/react-native-sdk 6.0.0-alpha.9 → 6.0.0-beta.1

package/lib/hooks/extensions/use-register-extension.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Registration state for extension registration lifecycle
+ */
+export type RegistrationState = 'unregistered' | 'registering' | 'registered';
+/**
+ * Creates a registration control system to prevent race conditions between multiple hook instances.
+ * Uses closure to encapsulate state and provide controlled access.
+ *
+ * CRITICAL: Must use module-level closure approach for race prevention. Context-based coordination
+ * fails because React context updates are async/batched, creating race windows where multiple
+ * components can read identical state and all proceed with registration simultaneously.
+ * Only synchronous, module-level state can provide atomic coordination across component instances.
+ *
+ * @param extensionName - The name of the extension being registered
+ * @returns Registration control interface with methods to manage concurrent registrations
+ */
+declare function createRegistrationControl(): {
+    /**
+     * Checks if a registration is currently in progress
+     * @returns True if registration is active, false otherwise
+     */
+    isCurrentlyRegistering(): boolean;
+    /**
+     * Starts a registration process, ensuring only one can run at a time
+     * @param registrationFn - The async function to execute for registration
+     * @returns Promise that resolves when registration completes
+     */
+    startRegistration(registrationFn: () => Promise<void>): Promise<void>;
+    /**
+     * Resets the registration state (useful when bridge becomes unavailable)
+     */
+    reset(): void;
+};
+/**
+ * Gets or creates a registration control for a specific extension
+ * @param extensionName - The name of the extension
+ * @returns Registration control instance for the extension
+ */
+declare function getRegistrationControl(extensionName: string): ReturnType<typeof createRegistrationControl>;
+export { createRegistrationControl, getRegistrationControl };
+/**
+ * Configuration for the extension registration hook
+ */
+export interface UseRegisterExtensionConfig {
+    /**
+     * The name of the extension to register (e.g., 'blue-dot', 'dynamic-focus')
+     */
+    extensionName: string;
+    /**
+     * Function that returns the registration script for the extension
+     */
+    getRegistrationScript: () => string;
+    /**
+     * Optional logger for debugging
+     */
+    logger?: {
+        log: (...messages: string[]) => void;
+        error: (message: string, error?: unknown) => void;
+    };
+}
+/**
+ * React hook for registering extensions with the WebView bridge
+ *
+ * This hook handles the complete extension registration lifecycle:
+ * - Monitors bridge readiness state
+ * - Checks if extension is already registered to avoid duplicates
+ * - Injects registration script when needed
+ * - Updates extension state in shared context
+ * - Handles all registration errors gracefully
+ *
+ * Multiple hooks can use this safely - the registration logic is idempotent
+ * and will only register the extension once per bridge lifecycle.
+ *
+ * @param config - Configuration for the extension registration
+ * @returns void - Hook performs registration as side effect only
+ *
+ * @example
+ * ```tsx
+ * function MyExtensionHook() {
+ *   useRegisterExtension({
+ *     extensionName: 'my-extension',
+ *     getRegistrationScript: () => 'extension script here'
+ *   });
+ *
+ *   // Read isReady from context extensions
+ *   const { extensions } = useContext(MappedinContext);
+ *   const isReady = extensions?.['my-extension']?.isReady || false;
+ * }
+ * ```
+ */
+export declare function useRegisterExtension(config: UseRegisterExtensionConfig): void;
+//# sourceMappingURL=use-register-extension.d.ts.map

package/lib/hooks/extensions/use-register-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-register-extension.d.ts","sourceRoot":"","sources":["../../../src/hooks/extensions/use-register-extension.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,aAAa,GAAG,YAAY,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,iBAAS,yBAAyB;IAKhC;;;OAGG;8BACuB,OAAO;IAIjC;;;;OAIG;sCACqC,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAe3E;;OAEG;aACM,IAAI;EAKd;AAOD;;;;GAIG;AACH,iBAAS,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,yBAAyB,CAAC,CAKnG;AAGD,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,qBAAqB,EAAE,MAAM,MAAM,CAAC;IAEpC;;OAEG;IACH,MAAM,CAAC,EAAE;QACR,GAAG,EAAE,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;QACrC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;KAClD,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAyH7E"}

package/lib/hooks/use-bridge.d.ts

@@ -0,0 +1,18 @@
+import type { WebView, WebViewMessageEvent } from 'react-native-webview';
+import type { Instruction } from '@mappedin/webview-bridge';
+/**
+ * React hook for communicating with a WebView or iframe using a bridge pattern.
+ * Automatically detects platform and uses appropriate communication method.
+ *
+ * @param container - The WebView instance (React Native) or HTMLIFrameElement (web) - can be null
+ * @returns An object containing the instruct function, handleMessage callback, cleanup function, and isReady state
+ */
+export declare function useBridge(container: WebView | HTMLIFrameElement | null): {
+    instruct: <T = any>(instruction: Instruction) => Promise<T>;
+    handleMessage: (event: WebViewMessageEvent | MessageEvent) => void;
+    destroy: () => void;
+    isReady: boolean;
+    injectJavaScript: (src: string) => Promise<void>;
+};
+export type UseBridgeHook = ReturnType<typeof useBridge>;
+//# sourceMappingURL=use-bridge.d.ts.map

package/lib/hooks/use-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-bridge.d.ts","sourceRoot":"","sources":["../../src/hooks/use-bridge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAmE5D;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI;eA0CpE,CAAC,qBAAqB,WAAW,KAAG,OAAO,CAAC,CAAC,CAAC;2BA9BN,mBAAmB,GAAG,YAAY;;;4BAkGrE,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;EAiE7B;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC"}

package/lib/hooks/use-event-callback.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @internal curently this is marked as internal. Until we want to promote customer to build their own extensions.
+ */
+export interface UseEventCallbackOptions<T = any> {
+    eventKey: string;
+    callback: (payload: T) => void;
+    setupScript: () => string;
+    cleanupScript: () => string;
+    shouldInject?: boolean;
+}
+/**
+ * Shared hook for managing event callbacks with reference counting
+ *
+ * This hook handles the common pattern of:
+ * - Registering callbacks with React Native event control
+ * - Reference counting to avoid duplicate WebView listeners
+ * - JavaScript injection for setup/cleanup only when needed
+ * - Stable callback handling that survives callback updates
+ *
+ * @param options Configuration for the event callback
+ * @internal curently this is marked as internal. Until we want to promote customer to build their own extensions.
+ */
+export declare function useEventCallback<T = any>({ eventKey, callback, setupScript, cleanupScript, shouldInject, }: UseEventCallbackOptions<T>): void;
+//# sourceMappingURL=use-event-callback.d.ts.map

package/lib/hooks/use-event-callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-event-callback.d.ts","sourceRoot":"","sources":["../../src/hooks/use-event-callback.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,GAAG;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAC/B,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAAE,EACzC,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,aAAa,EACb,YAAmB,GACnB,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,IAAI,CAsDnC"}

package/lib/hooks/use-map-view-event.d.ts

@@ -0,0 +1,27 @@
+import type { TEvents } from '@mappedin/mappedin-js';
+type TEventPayload<EventName extends keyof TEvents> = TEvents[EventName] extends {
+    data: null;
+} ? TEvents[EventName]['data'] : TEvents[EventName];
+/**
+ * Hook to subscribe to an event on the MapView in React Native.
+ *
+ * This hook uses the MapView's .on() and .off() methods to subscribe to events
+ * on the MapView instance running in the WebView.
+ *
+ * @param event - The event to listen for.
+ * @param callback - The callback to call when the event is triggered.
+ *
+ * @category Hooks
+ *
+ * @example
+ * ```tsx
+ * useMapViewEvent('click', event => {
+ *  const { coordinate } = event;
+ *  const { latitude, longitude } = coordinate;
+ *  console.log(`Map was clicked at ${latitude}, ${longitude}`);
+ * });
+ * ```
+ */
+export declare function useMapViewEvent<T extends keyof TEvents>(event: T, callback: (payload: TEventPayload<T>) => void): void;
+export {};
+//# sourceMappingURL=use-map-view-event.d.ts.map

package/lib/hooks/use-map-view-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-map-view-event.d.ts","sourceRoot":"","sources":["../../src/hooks/use-map-view-event.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,KAAK,aAAa,CAAC,SAAS,SAAS,MAAM,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC,SAAS;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAC5F,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,SAAS,CAAC,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,QAwC/G"}

package/lib/hooks/use-map.d.ts

@@ -0,0 +1,72 @@
+import type { WebView, WebViewMessageEvent } from 'react-native-webview';
+import type { Mappedin } from '../types';
+import type { MapViewControl } from '../controls/map-view-control';
+import type { EventControl } from '../controls/event-control';
+import type { PubSub } from '@mappedin/mappedin-js';
+import type { BaseExtensionState, ExtensionRegistry, ExtensionsObject } from '../extension-registry';
+import type { useBridge } from './use-bridge';
+interface WebViewMessageEventPayload {
+    'webview-message-received': WebViewMessageEvent;
+}
+export declare const MappedinContext: import("react").Context<{
+    mapData?: Mappedin.MapData;
+    mapView?: MapViewControl;
+    /**
+     * Event control system for managing event callbacks.
+     * @internal
+     */
+    _events?: EventControl;
+    /**
+     * Container instance for bridge communication (WebView on native, HTMLIFrameElement on web).
+     * @internal
+     */
+    _webView?: WebView | HTMLIFrameElement | null;
+    /**
+     * PubSub instance for WebView message events.
+     * @internal
+     */
+    _webViewMessagePubSub?: PubSub<WebViewMessageEventPayload>;
+    bridge?: ReturnType<typeof useBridge>;
+    /**
+     * Extension state storage for various extensions.
+     * Each extension can store its own state here.
+     */
+    extensions: ExtensionsObject;
+    /**
+     * Function to update extension state.
+     * @param name - The extension name (must be a registered extension)
+     * @param stateOrUpdater - Either the new state directly, or a callback function that receives the previous state and returns the new state
+     */
+    updateExtensionState: keyof ExtensionRegistry extends never ? (name: string, stateOrUpdater: BaseExtensionState | ((prevState: BaseExtensionState) => BaseExtensionState)) => void : <K extends keyof ExtensionRegistry>(name: K, stateOrUpdater: Partial<ExtensionRegistry[K]> | ((prevState: ExtensionRegistry[K]) => Partial<ExtensionRegistry[K]>)) => void;
+}>;
+/**
+ * Hook to get the MapData and MapView instances from the MapView context.
+ *
+ * This hook provides access to the mapData and mapView instances that are
+ * created and managed by the MapView component. It ensures that the hook
+ * is used within a MapView component context.
+ *
+ * @throws {MapViewNullError} When used outside of a MapView component or when mapData/mapView are not yet initialized
+ *
+ * @returns Object containing mapData and mapView instances
+ *
+ * @example
+ * ```tsx
+ * function MyMapComponent() {
+ *   const { mapData, mapView } = useMap();
+ *
+ *   useEffect(() => {
+ *     // Use mapView to interact with the map
+ *     mapView.Camera.animateTo({ center: mapData.getByType('space')[0] });
+ *   }, [mapData, mapView]);
+ *
+ *   return <Text>Map is ready!</Text>;
+ * }
+ * ```
+ */
+export declare function useMap(): {
+    mapData: Mappedin.MapData;
+    mapView: MapViewControl;
+};
+export {};
+//# sourceMappingURL=use-map.d.ts.map

package/lib/hooks/use-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-map.d.ts","sourceRoot":"","sources":["../../src/hooks/use-map.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAErG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,UAAU,0BAA0B;IACnC,0BAA0B,EAAE,mBAAmB,CAAC;CAChD;AAGD,eAAO,MAAM,eAAe;cACjB,QAAQ,CAAC,OAAO;cAChB,cAAc;IACxB;;;OAGG;cACO,YAAY;IACtB;;;OAGG;eACQ,OAAO,GAAG,iBAAiB,GAAG,IAAI;IAC7C;;;OAGG;4BACqB,MAAM,CAAC,0BAA0B,CAAC;aACjD,UAAU,CAAC,OAAO,SAAS,CAAC;IACrC;;;OAGG;gBACS,gBAAgB;IAC5B;;;;OAIG;0BACmB,MAAM,iBAAiB,SAAS,KAAK,GACxD,CACA,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,kBAAkB,GAAG,CAAC,CAAC,SAAS,EAAE,kBAAkB,KAAK,kBAAkB,CAAC,KACvF,IAAI,GACT,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAClC,IAAI,EAAE,CAAC,EACP,cAAc,EACX,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAC7B,CAAC,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,KAClE,IAAI;EAYX,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,MAAM,IAAI;IACzB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;CACxB,CAQA"}

package/lib/index.d.ts

@@ -0,0 +1,30 @@
+export { MapView } from './map-view';
+export type { MapViewProps } from './map-view';
+export { useMap, MappedinContext } from './hooks/use-map';
+export type { MapViewControl, Promisify, PromisifiedUpdateState } from './controls/map-view-control';
+export type { ExtensionRegistry } from './extension-registry';
+export { useMapViewEvent } from './hooks/use-map-view-event';
+export { useEventCallback } from './hooks/use-event-callback';
+export type { UseEventCallbackOptions } from './hooks/use-event-callback';
+export { Marker } from './components/marker';
+export type { MarkerProps } from './components/marker';
+export { Label } from './components/label';
+export type { LabelProps } from './components/label';
+export { Path } from './components/path';
+export type { PathProps } from './components/path';
+export { Shape } from './components/shape';
+export type { ShapeProps } from './components/shape';
+export type { Navigation } from './controls/map-view-control';
+export { Model } from './components/model';
+export type { ModelProps } from './components/model';
+export { setLoggerLevel } from './utils';
+export { createEventSetupScript, createEventCleanupScript } from './utils/extension-event-scripts';
+export type { EventScriptOptions } from './utils/extension-event-scripts';
+import type { hydrateMapData as HydrateMapData, unzipAndParseMVFv2 as UnzipAndParseMVFv2 } from '@mappedin/mappedin-js';
+export type { BaseExtensionState } from './extension-registry';
+export { useBridge } from './hooks/use-bridge';
+export { useRegisterExtension } from './hooks/extensions/use-register-extension';
+export type { UseRegisterExtensionConfig, RegistrationState } from './hooks/extensions/use-register-extension';
+export declare const hydrateMapData: typeof HydrateMapData;
+export declare const unzipAndParseMVFv2: typeof UnzipAndParseMVFv2;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrG,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,YAAY,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AACnG,YAAY,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAM1E,OAAO,KAAK,EAAE,cAAc,IAAI,cAAc,EAAE,kBAAkB,IAAI,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACxH,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,YAAY,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAE/G,eAAO,MAAM,cAAc,EAAE,OAAO,cAAgC,CAAC;AACrE,eAAO,MAAM,kBAAkB,EAAE,OAAO,kBAAwC,CAAC"}