@tracktor/map 0.1.0 → 0.1.1

package/dist/components/MarkerMap/MarkerMap.d.ts

@@ -1,3 +1,58 @@
 import { MarkerMapProps } from '../../types/MarkerMap.tsx';
+/**
+ * MarkerMap is a reusable React component that displays an interactive Mapbox map
+ * with customizable markers and behavior.
+ *
+ * It supports features like:
+ * - Auto-fitting bounds to markers
+ * - Custom marker icons and tooltips
+ * - Light/dark theming
+ * - Fly animations and zooming
+ * - Popup display (on click or hover)
+ * - Custom styling for the map container
+ * - Manual or automatic control of map centering and zoom
+ *
+ * @param {object} props - Props used to configure the map rendering.
+ * @param {boolean} [props.fitBounds] - If true, automatically adjusts the viewport to fit all markers.
+ * @param {number} [props.fitBoundsPadding] - Padding in pixels when fitting bounds to markers.
+ * @param {LngLatLike | number[]} [props.center] - Initial center of the map [lng, lat].
+ * @param {string} [props.mapStyle] - Mapbox style URL or identifier (e.g. "mapbox://styles/mapbox/streets-v11").
+ * @param {number} [props.zoom] - Initial zoom level of the map.
+ * @param {number} [props.zoomFlyFrom] - Zoom level to use before initiating a flyTo animation.
+ * @param {string} [props.popupMaxWidth] - Maximum width of popups (e.g., "200px").
+ * @param {number | string} [props.width="100%"] - Width of the map container.
+ * @param {number | string} [props.height=300] - Height of the map container.
+ * @param {boolean} [props.loading] - Optional flag indicating if the map is in loading state.
+ * @param {string} [props.markerImageURL] - URL of a custom image used for default marker icons.
+ * @param {SxProps} [props.containerStyle] - Style object (MUI `sx`) to customize the map container.
+ * @param {boolean} [props.disableFlyTo] - If true, disables flyTo animation when focusing on a marker.
+ * @param {number} [props.flyToDuration] - Duration of fly animation in milliseconds.
+ * @param {number} [props.fitBoundDuration] - Duration of fitBounds animation in milliseconds.
+ * @param {boolean} [props.square] - If true, forces the map container to be a square.
+ * @param {number | string} [props.openPopup] - ID of the marker whose popup should be open by default.
+ * @param {boolean} [props.openPopupOnHover] - If true, opens the popup on marker hover instead of click.
+ * @param {MarkerProps[]} [props.markers] - Array of marker objects to render on the map.
+ * @param {(lng: number, lat: number) => void} [props.onMapClick] - Callback triggered when the map is clicked.
+ * @param {"light" | "dark" | ThemeOptions} [props.theme] - Optional theme override for map rendering.
+ *
+ * @returns {JSX.Element} The rendered map component with optional markers and behavior.
+ *
+ * @example
+ * ```tsx
+ * <MarkerMap
+ *   center={[2.3488, 48.8534]}
+ *   zoom={13}
+ *   fitBounds
+ *   markers={[
+ *     { id: 1, lat: 48.8534, lng: 2.3488, name: "Marker 1" },
+ *     { id: 2, lat: 48.8566, lng: 2.3522, name: "Marker 2" },
+ *   ]}
+ *   openPopupOnHover
+ *   popupMaxWidth="250px"
+ *   mapStyle="mapbox://styles/mapbox/light-v10"
+ *   theme="light"
+ * />
+ * ```
+ */
 declare const MarkerMap: ({ containerStyle, square, theme, height, width, ...props }: MarkerMapProps) => import("react/jsx-runtime").JSX.Element;
 export default MarkerMap;

package/dist/components/MarkerMap/useMarkerMap.d.ts

@@ -2,6 +2,18 @@ import { Map } from 'mapbox-gl';
 import { MarkerMapProps } from '../../types/MarkerMap.tsx';
 export declare const DEFAULT_CENTER_LNG = 2.333;
 export declare const DEFAULT_CENTER_LAT = 46.8677;
+/**
+ * Custom React hook to integrate and manage a Mapbox map instance with dynamic markers,
+ * popups, zooming, centering, and click handling.
+ *
+ * This hook:
+ * - Initializes a Mapbox map inside a container
+ * - Loads and displays markers on the map
+ * - Adds popups to specific markers when requested
+ * - Adjusts the map center or fits bounds based on markers
+ * - Handles map click events with a provided callback
+ * - Supports customizable flyTo behavior, zoom levels, and map style
+ */
 declare const useMarkerMap: ({ markers, loading, center, flyToDuration, fitBoundDuration, fitBounds, disableFlyTo, fitBoundsPadding, mapStyle, zoom, zoomFlyFrom, openPopup, onMapClick, }: MarkerMapProps) => {
     loading: boolean | undefined;
     map: import('react').RefObject<Map | null>;

package/dist/types/Markers.d.ts

@@ -1,15 +1,56 @@
 import { default as React, ReactNode } from 'react';
 export interface MarkerProps {
+    /**
+     * Optional unique identifier for the marker.
+     */
     id?: number | string;
+    /**
+     * Longitude coordinate of the marker.
+     * Should be a number; using 'unknown' allows flexibility but requires validation.
+     */
     lng: number | unknown;
+    /**
+     * Latitude coordinate of the marker.
+     * Should be a number; using 'unknown' allows flexibility but requires validation.
+     */
     lat: number | unknown;
+    /**
+     * Optional tooltip element displayed when hovering or clicking on the marker.
+     * Can be a React component or any ReactNode.
+     */
     Tooltip?: ReactNode;
+    /**
+     * URL or name of the icon image to display for the marker.
+     * Only used if no IconComponent is provided.
+     */
     iconImage?: string;
+    /**
+     * Optional size (scale) of the marker icon.
+     */
     size?: number;
+    /**
+     * Z-index to control layering of the marker relative to others.
+     */
     zIndex?: number;
+    /**
+     * Function to call when the marker is clicked.
+     */
     onClick?: () => void;
+    /**
+     * Optional type/category of the marker (e.g., 'restaurant', 'user', etc.).
+     */
     type?: string;
+    /**
+     * Optional display name for the marker.
+     */
     name?: string;
+    /**
+     * Optional custom React component to use as the marker icon.
+     * Overrides iconImage if provided.
+     */
     IconComponent?: React.ComponentType<any>;
+    /**
+     * Optional props to pass to the IconComponent.
+     */
     iconProps?: Record<string, any>;
 }

package/dist/utils/addPopup.d.ts

@@ -6,10 +6,38 @@ interface AddPopupProps {
     map: MutableRefObject<Map | null>;
 }
 /**
- * Add a popup on the map at the provided coordinates with the provided tooltip (ReactNode)
- * @param map
- * @param tooltip
- * @param coordinates
+ * Adds a React-based popup to a Mapbox map
+ *
+ * This function creates and displays a popup on a Mapbox map with custom content rendered
+ * using React. The popup includes a styled close button and properly handles React component
+ * lifecycle to prevent memory leaks.
+ *
+ * @param {Object} options - The configuration options
+ * @param {MutableRefObject<Map | null>} options.map - Reference to the Mapbox map instance
+ * @param {ReactNode} [options.tooltip] - React node to render inside the popup
+ * @param {[number, number]} [options.coordinates] - [longitude, latitude] where the popup should appear
+ * @returns {void}
+ *
+ * @example
+ * // Basic usage
+ * addPopup({
+ *   map: mapRef,
+ *   coordinates: [-73.985, 40.748],
+ *   tooltip: <div>Empire State Building</div>
+ * });
+ *
+ * @example
+ * // With complex React content
+ * addPopup({
+ *   map: mapRef,
+ *   coordinates: marker.position,
+ *   tooltip: (
+ *     <InfoWindow title={marker.title}>
+ *       <p>{marker.description}</p>
+ *       <button onClick={handleAction}>More Info</button>
+ *     </InfoWindow>
+ *   )
+ * });
  */
 declare const addPopup: ({ map, tooltip, coordinates }: AddPopupProps) => void;
 export default addPopup;

package/dist/utils/coordinateConverter.d.ts

@@ -1,7 +1,16 @@
 import { LngLatLike } from 'mapbox-gl';
 /**
- * Cast the center to LngLatLike if it's an array (in right Coordinates system [lng, lat])
- * @param center
+ * Converts coordinates to a format compatible with Mapbox's LngLatLike type
+ *
+ * This utility function ensures coordinates are properly formatted for Mapbox operations.
+ * It handles different input formats and converts them to the expected LngLatLike format,
+ * which requires longitude and latitude values in the form [lng, lat].
+ *
+ * @param {LngLatLike | number[] | undefined} center - Coordinates to convert, which can be:
+ *   - LngLatLike object (already in Mapbox format)
+ *   - number array in [longitude, latitude] format
+ *   - undefined (no coordinates provided)
+ * @returns {LngLatLike | undefined} - Properly formatted coordinates or undefined if invalid
  */
 declare const coordinateConverter: (center: LngLatLike | number[] | undefined) => LngLatLike | undefined;
 export default coordinateConverter;

package/dist/utils/handleMapClick.d.ts

@@ -7,9 +7,20 @@ export interface HandleMapClickProps {
     event: MapMouseEvent;
 }
 /**
- * Handle the map click event to display a popup on the clicked marker
- * @param map
- * @param markers
- * @param event
+ * Handles map click events to display popups on clicked markers
+ *
+ * This function:
+ * 1. Identifies if a marker was clicked within the map
+ * 2. Extracts the coordinates and properties of the clicked marker
+ * 3. Finds the corresponding marker in the provided markers array
+ * 4. Displays a popup at the marker's location with its tooltip content
+ *
+ * The function only processes clicks on layers whose IDs start with "marker-".
+ *
+ * @param {Object} options - The click handler configuration
+ * @param {MutableRefObject<Map | null>} options.map - Reference to the Mapbox map instance
+ * @param {MarkerProps[]} options.markers - Array of marker objects with tooltips and properties
+ * @param {MapMouseEvent} options.event - The Mapbox mouse event triggered by clicking
+ * @returns {void}
  */
 export declare const handleMapClick: ({ map, markers, event }: HandleMapClickProps) => void;

package/dist/utils/loadMarkers.d.ts

@@ -13,10 +13,28 @@ interface LoadMarkersProps {
     markers: MarkerProps[];
 }
 /**
- * Assign the markers style based on provided palette and type
- * @param palette - The color palette to use
- * @param type - The marker type (e.g., "dropOff")
- * @returns Style object for the marker
+ * Generates visual styles for map markers based on theme palette and marker type
+ *
+ * Creates consistent styling for different marker types with:
+ * - Dynamic color theming (light/dark mode support)
+ * - Type-specific visual differentiation
+ * - Responsive sizing
+ *
+ * @param {Object} params - Configuration parameters
+ * @param {Palette} params.palette - Design system color palette
+ * @param {string} [params.type] - Optional marker type identifier (e.g. "dropOff")
+ *
+ * @returns {Object} Mapbox GL paint properties object containing:
+ *   - circle-color: Center fill color
+ *   - circle-radius: Size of marker
+ *   - circle-stroke-color: Border color
+ *   - circle-stroke-width: Border thickness
+ *
+ * @example
+ * const markerStyle = generateMarkers({
+ *   palette: theme.palette,
+ *   type: "dropOff"
+ * });
  */
 export declare const generateMarkers: ({ palette, type }: GenerateMarkersProps) => {
     "circle-color": string;
@@ -25,11 +43,19 @@ export declare const generateMarkers: ({ palette, type }: GenerateMarkersProps)
     "circle-stroke-width": number;
 };
 /**
- * Load GeoJSON markers on the map with the provided style
- * @param map - MapBox instance
- * @param setLoadingMapBox - Function to set loading state
- * @param palette - Color palette
- * @param markers - Array of marker objects
+ * Main entry point for loading markers onto a Mapbox GL map
+ *
+ * Orchestrates:
+ * - Data conversion to GeoJSON
+ * - Marker type classification
+ * - Parallel loading of different marker types
+ * - Loading state management
+ *
+ * @param {Object} params - Configuration parameters
+ * @param {MutableRefObject<Map|null>} params.map - React ref to Mapbox GL instance
+ * @param {function} params.setLoadingMapBox - Loading state callback
+ * @param {Palette} params.palette - Design system color palette
+ * @param {MarkerProps[]} params.markers - Array of marker definitions
  */
 export declare const loadMarkers: ({ map, setLoadingMapBox, palette, markers }: LoadMarkersProps) => void;
 export {};

package/dist/utils/mapOptions.d.ts

@@ -9,12 +9,37 @@ interface MapOptionsProps {
     zoomFlyFrom?: number;
 }
 /**
- * MapBox options to initialize the map
- * @param mapStyle
- * @param mapContainer
- * @param zoomFlyFrom
- * @param markers
- * @param center
+ * Generates configuration options for initializing a Mapbox map
+ *
+ * This utility function creates a standardized configuration object for Mapbox GL JS
+ * by processing various input parameters. It handles:
+ * - Center point calculation (with fallback to marker positions or default)
+ * - Container element reference validation
+ * - Style application
+ * - Initial zoom level
+ *
+ * @param {Object} params - Configuration parameters
+ * @param {string} params.mapStyle - Mapbox style URL or specification
+ * @param {React.RefObject} [params.mapContainer] - Reference to the DOM container element
+ * @param {number} [params.zoomFlyFrom] - Initial zoom level for fly-to animation
+ * @param {MarkerProps[]} [params.markers] - Array of marker definitions
+ * @param {LngLatLike|number[]} [params.center] - Optional center coordinates (either as LngLat object or [lng, lat] array)
+ *
+ * @returns {Object} Mapbox-compatible configuration object with:
+ *   - center: Calculated center coordinates
+ *   - container: Validated container reference
+ *   - cooperativeGestures: Enabled by default
+ *   - failIfMajorPerformanceCaveat: Disabled by default
+ *   - style: The provided map style
+ *   - zoom: Initial zoom level
+ *
+ * @example
+ * const options = mapOptions({
+ *   mapStyle: 'mapbox://styles/mapbox/streets-v11',
+ *   mapContainer: mapRef,
+ *   markers: [{ lat: 48.8584, lng: 2.2945 }],
+ *   zoomFlyFrom: 12
+ * });
  */
 declare const mapOptions: ({ mapStyle, mapContainer, zoomFlyFrom, markers, center }: MapOptionsProps) => {
     center: {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tracktor/map",
   "description": "A react library to easily display map with multiple tools",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "scripts": {
     "env:load": "./bin/load-env.sh",