@maplibre/maplibre-react-native 11.0.0-beta.27 → 11.0.0-beta.29

package/src/components/map/Map.tsx

@@ -28,6 +28,7 @@ import AndroidTextureMapViewNativeComponent from "./AndroidTextureMapViewNativeC
 import MapViewNativeComponent from "./MapViewNativeComponent";
 import NativeMapViewModule from "./NativeMapViewModule";
 import { LogManager } from "../../modules/log/LogManager";
+import type { BaseProps } from "../../types/BaseProps";
 import type { LngLat } from "../../types/LngLat";
 import type { LngLatBounds } from "../../types/LngLatBounds";
 import type { PixelPoint } from "../../types/PixelPoint";
@@ -44,12 +45,19 @@ const styles = StyleSheet.create({
   flex1: { flex: 1 },
 });
 
+/**
+ * Screen position for map ornaments (logo, compass, scale bar). Exactly one of
+ * `top` / `bottom` and one of `left` / `right` must be provided.
+ */
 export type OrnamentViewPosition =
   | { top: number; left: number }
   | { top: number; right: number }
   | { bottom: number; right: number }
   | { bottom: number; left: number };
 
+/**
+ * Current viewport state of the map.
+ */
 export type ViewState = {
   center: LngLat;
   zoom: number;
@@ -58,11 +66,18 @@ export type ViewState = {
   bounds: LngLatBounds;
 };
 
+/**
+ * Event emitted when the map viewport changes (pan, zoom, rotate, pitch).
+ */
 export type ViewStateChangeEvent = ViewState & {
   animated: boolean;
   userInteraction: boolean;
 };
 
+/**
+ * Options for querying rendered features at a screen point or within a bounding
+ * box.
+ */
 export type QueryRenderedFeaturesOptions = {
   /**
    * Filter expression to filter the queried features
@@ -82,7 +97,9 @@ export interface MapRef {
    * @returns Current center coordinates of the map
    *
    * @example
+   * ```ts
    * await mapRef.current?.getCenter();
+   * ```
    */
   getCenter(): Promise<LngLat>;
 
@@ -92,7 +109,9 @@ export interface MapRef {
    * @returns Current zoom level of the map
    *
    * @example
+   * ```ts
    * await mapRef.current?.getZoom();
+   * ```
    */
   getZoom(): Promise<number>;
 
@@ -102,7 +121,9 @@ export interface MapRef {
    * @returns Current bearing of the map
    *
    * @example
+   * ```ts
    * await mapRef.current?.getBearing();
+   * ```
    */
   getBearing(): Promise<number>;
 
@@ -112,7 +133,9 @@ export interface MapRef {
    * @returns Current pitch of the map
    *
    * @example
+   * ```ts
    * await mapRef.current?.getPitch();
+   * ```
    */
   getPitch(): Promise<number>;
 
@@ -122,7 +145,9 @@ export interface MapRef {
    * @returns Current bounds of the map
    *
    * @example
+   * ```ts
    * await mapRef.current?.getBounds();
+   * ```
    */
   getBounds(): Promise<LngLatBounds>;
 
@@ -132,7 +157,9 @@ export interface MapRef {
    * @returns Current view state of the map
    *
    * @example
+   * ```ts
    * await mapRef.current?.getViewState();
+   * ```
    */
   getViewState(): Promise<ViewState>;
 
@@ -143,7 +170,9 @@ export interface MapRef {
    * @returns Pixel point
    *
    * @example
+   * ```ts
    * await mapRef.current?.project([13.04214014753952, 47.80554907882145]);
+   * ```
    */
   project(lngLat: LngLat): Promise<PixelPoint>;
 
@@ -154,7 +183,9 @@ export interface MapRef {
    * @returns Geographic coordinate
    *
    * @example
+   * ```ts
    * await mapRef.current?.unproject([280, 640]);
+   * ```
    */
   unproject(point: PixelPoint): Promise<LngLat>;
 
@@ -164,13 +195,12 @@ export interface MapRef {
    * @returns Queried features
    *
    * @example
-   * await mapRef.current?.queryRenderedFeatures(
-   *   [240, 640],
-   *   {
-   *     filter: ["==", "type", "Point"],
-   *     layers: ["restaurants", "shops"],
-   *   },
-   * );
+   * ```ts
+   * await mapRef.current?.queryRenderedFeatures([240, 640], {
+   *   filter: ["==", "type", "Point"],
+   *   layers: ["restaurants", "shops"],
+   * });
+   * ```
    */
   queryRenderedFeatures(
     pixelPoint: PixelPoint,
@@ -183,13 +213,12 @@ export interface MapRef {
    * @returns Queried features
    *
    * @example
-   * await mapRef.current?.queryRenderedFeatures(
-   *   [100, 100, 400, 400],
-   *   {
-   *     filter: ["==", "type", "Point"],
-   *     layers: ["restaurants", "shops"],
-   *   },
-   * );
+   * ```ts
+   * await mapRef.current?.queryRenderedFeatures([100, 100, 400, 400], {
+   *   filter: ["==", "type", "Point"],
+   *   layers: ["restaurants", "shops"],
+   * });
+   * ```
    */
   queryRenderedFeatures(
     pixelPointBounds: PixelPointBounds,
@@ -202,12 +231,12 @@ export interface MapRef {
    * @returns Queried features
    *
    * @example
-   * await mapRef.current?.queryRenderedFeatures(
-   *   {
-   *     filter: ["==", "type", "Point"],
-   *     layers: ["restaurants", "shops"],
-   *   },
-   * );
+   * ```ts
+   * await mapRef.current?.queryRenderedFeatures({
+   *   filter: ["==", "type", "Point"],
+   *   layers: ["restaurants", "shops"],
+   * });
+   * ```
    */
   queryRenderedFeatures(
     options?: QueryRenderedFeaturesOptions,
@@ -229,7 +258,9 @@ export interface MapRef {
    * @param sourceLayer - Identifier of the target source-layer (e.g. 'building')
    *
    * @example
-   * await mapRef.current?.setSourceVisibility(false, 'composite', 'building')
+   * ```ts
+   * await mapRef.current?.setSourceVisibility(false, "composite", "building");
+   * ```
    */
   setSourceVisibility(
     visible: boolean,
@@ -245,7 +276,7 @@ export interface MapRef {
   showAttribution(): Promise<void>;
 }
 
-export interface MapProps extends ViewProps {
+export interface MapProps extends BaseProps, ViewProps {
   /**
    * Style for wrapping React Native View
    *
@@ -265,7 +296,9 @@ export interface MapProps extends ViewProps {
    * Controls the light source for extruded geometries.
    *
    * @example
+   * ```tsx
    * light={{ position: [1.5, 90, 80], color: "#ffffff", intensity: 0.5 }}
+   * ```
    */
   light?: LightSpecification;
 
@@ -276,14 +309,14 @@ export interface MapProps extends ViewProps {
   contentInset?: ViewPadding;
 
   /**
-   * iOS: The preferred frame rate at which the map view is rendered. The default
-   * value for this property is MLNMapViewPreferredFramesPerSecondDefault, which
-   * will adaptively set the preferred frame rate based on the capability of the
-   * user’s device to maintain a smooth experience. This property can be set to
-   * arbitrary integer values.
+   * **iOS**: The preferred frame rate at which the map view is rendered. The
+   * default value for this property is MLNMapViewPreferredFramesPerSecondDefault,
+   * which will adaptively set the preferred frame rate based on the capability of
+   * the user’s device to maintain a smooth experience. This property can be set
+   * to arbitrary integer values.
    *
-   * Android: The maximum frame rate at which the map view is rendered, but it
-   * can't excess the ability of device hardware. This property can be set to
+   * **Android**: The maximum frame rate at which the map view is rendered, but it
+   * can't exceed the ability of device hardware. This property can be set to
    * arbitrary integer values.
    */
   preferredFramesPerSecond?: number;
@@ -347,7 +380,9 @@ export interface MapProps extends ViewProps {
    * Positions the attribution button
    *
    * @example Position in the top-left corner
+   * ```ts
    * { top: 8, left: 8 }
+   * ```
    */
   attributionPosition?: OrnamentViewPosition;
 
@@ -360,7 +395,9 @@ export interface MapProps extends ViewProps {
    * Positions the logo
    *
    * @example Position in the top-left corner
+   * ```ts
    * { top: 8, left: 8 }
+   * ```
    */
   logoPosition?: OrnamentViewPosition;
 
@@ -373,7 +410,9 @@ export interface MapProps extends ViewProps {
    * Positions the compass
    *
    * @example Position in the top-left corner
+   * ```ts
    * { top: 8, left: 8 }
+   * ```
    */
   compassPosition?: OrnamentViewPosition;
 
@@ -393,7 +432,9 @@ export interface MapProps extends ViewProps {
    * Positions the scale bar. Android only supports top-left corner.
    *
    * @example Position in the bottom-left corner
+   * ```ts
    * { bottom: 8, left: 8 }
+   * ```
    */
   scaleBarPosition?: OrnamentViewPosition;
 
@@ -501,7 +542,12 @@ export interface MapProps extends ViewProps {
 }
 
 /**
- * MapLibre Native Map
+ * A view of a MapLibre Native Map.
+ *
+ * @example Rendering a basic Map
+ * ```tsx
+ * <Map mapStyle="https://demotiles.maplibre.org/style.json" />;
+ * ```
  */
 export const Map = memo(
   ({ androidView = "surface", style, ref, ...props }: MapProps) => {

package/src/components/sources/geojson-source/GeoJSONSource.tsx

@@ -17,7 +17,7 @@ import GeoJSONSourceNativeComponent from "./GeoJSONSourceNativeComponent";
 import NativeGeoJSONSourceModule from "./NativeGeoJSONSourceModule";
 import { useFrozenId } from "../../../hooks/useFrozenId";
 import { type BaseProps } from "../../../types/BaseProps";
-import type { PressableSourceProps } from "../../../types/sources/PressableSourceProps";
+import type { PressableSourceProps } from "../../../types/PressableSourceProps";
 import { cloneReactChildrenWithProps } from "../../../utils";
 import { findNodeHandle } from "../../../utils/findNodeHandle";
 import { getNativeFilter } from "../../../utils/getNativeFilter";

package/src/components/sources/vector-source/VectorSource.tsx

@@ -14,20 +14,22 @@ import NativeVectorSourceModule from "./NativeVectorSourceModule";
 import VectorSourceNativeComponent from "./VectorSourceNativeComponent";
 import { useFrozenId } from "../../../hooks/useFrozenId";
 import { type BaseProps } from "../../../types/BaseProps";
-import type { PressableSourceProps } from "../../../types/sources/PressableSourceProps";
+import type { PressableSourceProps } from "../../../types/PressableSourceProps";
 import { cloneReactChildrenWithProps } from "../../../utils";
 import { findNodeHandle } from "../../../utils/findNodeHandle";
 import { getNativeFilter } from "../../../utils/getNativeFilter";
 
 export interface VectorSourceRef {
   /**
-   * Returns all features that match the query parameters regardless of whether or
-   * not the feature is currently rendered on the map. The domain of the query
+   * Returns all features that match the query parameters regardless of whether
+   * the feature is currently rendered on the map. The domain of the query
    * includes all currently-loaded vector tiles and GeoJSON source tiles. This
-   * function does not check tiles outside of the visible viewport.
+   * function does not check tiles outside the visible viewport.
    *
    * @example
-   * vectorSource.features(['id1', 'id2'])
+   * ```ts
+   * vectorSource.querySourceFeatures({ sourceLayer: "some-source-layer" });
+   * ```
    */
   querySourceFeatures(options: {
     sourceLayer: string;
@@ -49,8 +51,8 @@ export interface VectorSourceProps extends BaseProps, PressableSourceProps {
 
   /**
    * An array of tile URL templates. If multiple endpoints are specified, clients
-   * may use any combination of endpoints. Example:
-   * https://example.com/vector-tiles/{z}/{x}/{y}.pbf
+   * may use any combination of endpoints. Common format should be:
+   * `https://example.com/vector-tiles/{z}/{x}/{y}.pbf` .
    */
   tiles?: string[];
 

package/src/modules/offline/OfflineManager.ts

@@ -83,16 +83,24 @@ class OfflineManager {
    * @returns The created offline pack with its generated ID.
    *
    * @example
-   * const progressListener = (offlineRegion, status) => console.log(offlineRegion, status);
-   * const errorListener = (offlineRegion, error) => console.log(offlineRegion, error);
+   * ```ts
+   * const progressListener = (offlineRegion, status) =>
+   *   console.log(offlineRegion, status);
+   * const errorListener = (offlineRegion, error) =>
+   *   console.log(offlineRegion, error);
    *
-   * const offlinePack = await OfflineManager.createPack({
-   *   mapStyle: 'https://demotiles.maplibre.org/tiles/tiles.json',
-   *   minZoom: 14,
-   *   maxZoom: 20,
-   *   bounds: [west, south, east, north],
-   *   metadata: { customValue: 'myValue' }
-   * }, progressListener, errorListener)
+   * const offlinePack = await OfflineManager.createPack(
+   *   {
+   *     mapStyle: "https://demotiles.maplibre.org/tiles/tiles.json",
+   *     minZoom: 14,
+   *     maxZoom: 20,
+   *     bounds: [west, south, east, north],
+   *     metadata: { customValue: "myValue" },
+   *   },
+   *   progressListener,
+   *   errorListener,
+   * );
+   * ```
    */
   async createPack(
     options: OfflinePackCreateOptions,
@@ -131,7 +139,9 @@ class OfflineManager {
    * @param id - ID of the OfflinePack.
    *
    * @example
-   * await OfflineManager.invalidatePack(pack.id)
+   * ```ts
+   * await OfflineManager.invalidatePack(pack.id);
+   * ```
    */
   async invalidatePack(id: string): Promise<void> {
     await this.initialize();
@@ -147,7 +157,9 @@ class OfflineManager {
    * @param id - ID of the OfflinePack.
    *
    * @example
-   * await OfflineManager.deletePack(pack.id)
+   * ```ts
+   * await OfflineManager.deletePack(pack.id);
+   * ```
    */
   async deletePack(id: string): Promise<void> {
     await this.initialize();
@@ -167,7 +179,9 @@ class OfflineManager {
    * effects.
    *
    * @example
+   * ```ts
    * await OfflineManager.invalidateAmbientCache();
+   * ```
    */
   async invalidateAmbientCache(): Promise<void> {
     await this.initialize();
@@ -179,7 +193,9 @@ class OfflineManager {
    * decreases the amount of space that map resources take up on the device.
    *
    * @example
+   * ```ts
    * await OfflineManager.clearAmbientCache();
+   * ```
    */
   async clearAmbientCache(): Promise<void> {
     await this.initialize();
@@ -206,7 +222,9 @@ class OfflineManager {
    * offline packs, then reinitializes it.
    *
    * @example
+   * ```ts
    * await OfflineManager.resetDatabase();
+   * ```
    */
   async resetDatabase(): Promise<void> {
     await this.initialize();
@@ -229,7 +247,9 @@ class OfflineManager {
    * Retrieves an offline pack that is stored in the database by ID.
    *
    * @example
+   * ```ts
    * const offlinePack = await OfflineManager.getPack(offlinePack.id);
+   * ```
    */
   async getPack(id: string): Promise<OfflinePack> {
     await this.initialize();
@@ -248,7 +268,9 @@ class OfflineManager {
    * @param path - Path to offline tile db on file system.
    *
    * @example
+   * ```ts
    * await OfflineManager.mergeOfflineRegions(path);
+   * ```
    */
   async mergeOfflineRegions(path: string): Promise<void> {
     await this.initialize();
@@ -263,7 +285,9 @@ class OfflineManager {
    * @param limit - Map tile limit count.
    *
    * @example
+   * ```ts
    * OfflineManager.setTileCountLimit(1000);
+   * ```
    */
   setTileCountLimit(limit: number): void {
     NativeOfflineModule.setTileCountLimit(limit);
@@ -276,7 +300,9 @@ class OfflineManager {
    * @param throttleValue - Event throttle value in ms.
    *
    * @example
+   * ```ts
    * OfflineManager.setProgressEventThrottle(500);
+   * ```
    */
   setProgressEventThrottle(throttleValue: number): void {
     NativeOfflineModule.setProgressEventThrottle(throttleValue);
@@ -293,9 +319,12 @@ class OfflineManager {
    *   resource.
    *
    * @example
-   * const progressListener = (offlinePack, status) => console.log(offlinePack, status)
-   * const errorListener = (offlinePack, error) => console.log(offlinePack, error)
-   * OfflineManager.addListener(pack.id, progressListener, errorListener)
+   * ```ts
+   * const progressListener = (offlinePack, status) =>
+   *   console.log(offlinePack, status);
+   * const errorListener = (offlinePack, error) => console.log(offlinePack, error);
+   * OfflineManager.addListener(pack.id, progressListener, errorListener);
+   * ```
    */
   async addListener(
     id: string,
@@ -328,11 +357,13 @@ class OfflineManager {
    * @param packId - ID of the offline pack.
    *
    * @example
+   * ```ts
    * useEffect(() => {
    *   return () => {
    *     OfflineManager.removeListener(pack.id);
-   *   }
+   *   };
    * }, []);
+   * ```
    */
   removeListener(packId: string): void {
     delete this.progressListeners[packId];

package/src/modules/static-map/StaticMapManager.ts

@@ -81,10 +81,12 @@ class StaticMapManager {
   /**
    * Creates a static image of a map. Images are always in PNG format.
    *
-   * @example
-   * // Create static map with center, returning the URI to the temporary PNG file
+   * @param options -
+   *
+   * @example Create static map with center, returning the URI to the temporary PNG file
+   * ```ts
    * const uri = await StaticMapManager.createImage({
-   *   center: [-74.126410, 40.797968 ],
+   *   center: [-74.12641, 40.797968],
    *   zoom: 12,
    *   bearing: 20,
    *   pitch: 30,
@@ -93,15 +95,21 @@ class StaticMapManager {
    *   height: 64,
    *   output: "file",
    * });
+   * ```
    *
-   * // Create a static map with bounds, returning a base64 encoded PNG
+   * @example Create a static map with bounds, returning a base64 encoded PNG
+   * ```ts
    * const uri = await StaticMapManager.createImage({
-   *   bounds: [[-74.126410, 40.797968], [-74.143727, 40.772177]],
+   *   bounds: [
+   *     [-74.12641, 40.797968],
+   *     [-74.143727, 40.772177],
+   *   ],
    *   mapStyle: "https://demotiles.maplibre.org/style.json",
    *   width: 128,
    *   height: 64,
    *   output: "base64",
    * });
+   * ```
    */
   async createImage({
     mapStyle,

package/src/modules/transform-request/TransformRequestManager.ts

@@ -175,8 +175,13 @@ class TransformRequestManager {
    * });
    * ```
    *
-   * // Add apiKey to all requests (no match = applies to all)
-   * TransformRequestManager.addUrlSearchParam({ name: "apiKey", value: "your-api-key" });
+   * @example Add apiKey to all requests (no match = applies to all)
+   * ```ts
+   * TransformRequestManager.addUrlSearchParam({
+   *   name: "apiKey",
+   *   value: "your-api-key",
+   * });
+   * ```
    */
   addUrlSearchParam(options: UrlSearchParamOptions): string {
     const id = options.id ?? this.getId();

package/src/types/BaseProps.ts

@@ -1,3 +1,6 @@
+/**
+ * Base props supported by all components.
+ */
 export interface BaseProps {
   testID?: string;
 }

package/src/types/PressEvent.ts

@@ -1,6 +1,9 @@
 import type { LngLat } from "./LngLat";
 import type { PixelPoint } from "./PixelPoint";
 
+/**
+ * Event data for map press interactions.
+ */
 export interface PressEvent {
   /**
    * Geographic coordinates of the touch event

package/src/types/PressEventWithFeatures.ts

@@ -1,5 +1,8 @@
 import type { PressEvent } from "./PressEvent";
 
+/**
+ * Press event data enriched with GeoJSON features at the pressed location.
+ */
 export interface PressEventWithFeatures extends PressEvent {
   features: GeoJSON.Feature[];
 }

package/src/types/{sources/PressableSourceProps.ts → PressableSourceProps.ts}

@@ -1,8 +1,11 @@
 import type { NativeSyntheticEvent } from "react-native";
 
-import type { PressEventWithFeatures } from "../PressEventWithFeatures";
-import type { ViewPadding } from "../ViewPadding";
+import type { PressEventWithFeatures } from "./PressEventWithFeatures";
+import type { ViewPadding } from "./ViewPadding";
 
+/**
+ * Props shared by source components that support press interactions.
+ */
 export interface PressableSourceProps {
   /**
    * Emits on press when a child `Layer` within the hitbox has highest z-index

package/src/types/ViewPadding.ts

@@ -1,3 +1,6 @@
+/**
+ * Pixel insets used for view padding.
+ */
 export type ViewPadding = {
   top?: number;
   right?: number;

package/lib/commonjs/types/sources/PressableSourceProps.js.map

@@ -1 +0,0 @@
-{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["types/sources/PressableSourceProps.ts"],"mappings":"","ignoreList":[]}

package/lib/module/types/sources/PressableSourceProps.js.map

@@ -1 +0,0 @@
-{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["types/sources/PressableSourceProps.ts"],"mappings":"","ignoreList":[]}

package/lib/typescript/commonjs/types/sources/PressableSourceProps.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"PressableSourceProps.d.ts","sourceRoot":"","sources":["../../../../../src/types/sources/PressableSourceProps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC;IAExE;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}

package/lib/typescript/module/types/sources/PressableSourceProps.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"PressableSourceProps.d.ts","sourceRoot":"","sources":["../../../../../src/types/sources/PressableSourceProps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC;IAExE;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}