@maplibre/maplibre-react-native 11.0.0-alpha.2 → 11.0.0-alpha.21

package/src/components/sources/ShapeSource.tsx

@@ -0,0 +1,366 @@
+import {
+  Component,
+  forwardRef,
+  memo,
+  type ReactNode,
+  useImperativeHandle,
+  useRef,
+} from "react";
+import {
+  type NativeMethods,
+  NativeModules,
+  type NativeSyntheticEvent,
+  requireNativeComponent,
+} from "react-native";
+
+import { useNativeBridge } from "../../hooks/useNativeBridge";
+import { type BaseProps } from "../../types/BaseProps";
+import {
+  type ExpressionField,
+  type FilterExpression,
+} from "../../types/MapLibreRNStyles";
+import { type PressEventWithFeatures } from "../../types/PressEvent";
+import {
+  cloneReactChildrenWithProps,
+  isAndroid,
+  toJSONString,
+} from "../../utils";
+import { getFilter } from "../../utils/filterUtils";
+
+const MLRNModule = NativeModules.MLRNModule;
+export const NATIVE_MODULE_NAME = "MLRNShapeSource";
+
+interface NativeProps {
+  shape?: object | string;
+}
+
+type MLRNShapeSourceRefType = Component<NativeProps> & Readonly<NativeMethods>;
+
+export interface ShapeSourceProps extends BaseProps {
+  /**
+   * A string that uniquely identifies the source.
+   */
+  id: string;
+
+  /**
+   * An HTTP(S) URL, absolute file URL, or local file URL relative to the current application’s resource bundle.
+   */
+  url?: string;
+
+  /**
+   * The contents of the source. A shape can represent a GeoJSON geometry, a feature, or a feature colllection.
+   */
+  shape?:
+    | GeoJSON.GeometryCollection
+    | GeoJSON.Feature
+    | GeoJSON.FeatureCollection
+    | GeoJSON.Geometry;
+
+  /**
+   * Enables clustering on the source for point shapes.
+   */
+  cluster?: boolean;
+
+  /**
+   * Specifies the radius of each cluster if clustering is enabled.
+   * A value of 512 produces a radius equal to the width of a tile.
+   * The default value is 50.
+   */
+  clusterRadius?: number;
+
+  /**
+   * Specifies minimum number of points to form a cluster if clustering is enabled.
+   * The default value is 2.
+   */
+  clusterMinPoints?: number;
+
+  /**
+   * Specifies the maximum zoom level at which to cluster points if clustering is enabled.
+   * Defaults to one zoom level less than the value of maxZoomLevel so that, at the maximum zoom level,
+   * the shapes are not clustered.
+   */
+  clusterMaxZoomLevel?: number;
+
+  /**
+   * Specifies custom properties on the generated clusters if clustering
+   * is enabled, aggregating values from clustered points.
+   *
+   * Has the form `{ "property_name": [operator, map_expression]}`, where
+   *  `operator` is a custom reduce expression that references a special `["accumulated"]` value -
+   *   it accumulates the property value from clusters/points the cluster contains
+   *  `map_expression` produces the value of a single point
+   *
+   * @example `{ "resultingSum": [["+", ["accumulated"], ["get", "resultingSum"]], ["get", "scalerank"]] }`
+   *
+   */
+  clusterProperties?: { [propertyName: string]: ExpressionField };
+
+  /**
+   * Specifies the maximum zoom level at which to create vector tiles.
+   * A greater value produces greater detail at high zoom levels.
+   * The default value is 18.
+   */
+  maxZoomLevel?: number;
+
+  /**
+   * Specifies the size of the tile buffer on each side.
+   * A value of 0 produces no buffer. A value of 512 produces a buffer as wide as the tile itself.
+   * Larger values produce fewer rendering artifacts near tile edges and slower performance.
+   * The default value is 128.
+   */
+  buffer?: number;
+
+  /**
+   * Specifies the Douglas-Peucker simplification tolerance.
+   * A greater value produces simpler geometries and improves performance.
+   * The default value is 0.375.
+   */
+  tolerance?: number;
+
+  /**
+   * Whether to calculate line distance metrics.
+   * This is required for line layers that specify lineGradient values.
+   * The default value is false.
+   */
+  lineMetrics?: boolean;
+
+  /**
+   * Source press listener, gets called when a user presses one of the children layers only if that layer has a higher z-index than another source layers.
+   */
+  onPress?: (event: NativeSyntheticEvent<PressEventWithFeatures>) => void;
+
+  /**
+   * Overrides the default touch hitbox (44x44 pixels) for the source layers
+   */
+  hitbox?: {
+    /**
+     * `width` of hitbox
+     */
+    width: number;
+    /**
+     * `height` of hitbox
+     */
+    height: number;
+  };
+
+  children?: ReactNode;
+}
+
+export interface ShapeSourceRef {
+  features(filter?: FilterExpression): Promise<GeoJSON.FeatureCollection>;
+
+  getClusterExpansionZoom(feature: GeoJSON.Feature): Promise<number>;
+
+  getClusterLeaves(
+    feature: GeoJSON.Feature,
+    limit: number,
+    offset: number,
+  ): Promise<GeoJSON.FeatureCollection>;
+
+  getClusterChildren(
+    feature: GeoJSON.Feature,
+  ): Promise<GeoJSON.FeatureCollection>;
+
+  setNativeProps: (props: NativeProps) => void;
+
+  // this was required by existing test __tests__/utils/animated/AnimatedCoordinatesArray.test.js
+  _nativeRef: MLRNShapeSourceRefType | null;
+}
+
+/**
+ * ShapeSource is a map content source that supplies vector shapes to be shown on the map.
+ * The shape may be a url or a GeoJSON object
+ */
+export const ShapeSource = memo(
+  forwardRef<ShapeSourceRef, ShapeSourceProps>(
+    (
+      {
+        id: shapeId = MLRNModule.StyleSource.DefaultSourceID,
+        ...props
+      }: ShapeSourceProps,
+      ref,
+    ) => {
+      useImperativeHandle(ref, () => ({
+        ..._nativeRef.current,
+
+        /**
+         * Returns all features from the source that match the query parameters regardless of whether or not the feature is
+         * currently rendered on the map.
+         *
+         * @example
+         * shapeSource.features()
+         *
+         * @param  {Array=} filter - an optional filter statement to filter the returned Features.
+         * @return {GeoJSON.FeatureCollection}
+         */
+        features,
+
+        /**
+         * Returns the zoom needed to expand the cluster.
+         *
+         * @example
+         * const zoom = await shapeSource.getClusterExpansionZoom(clusterId);
+         *
+         * @param  {GeoJSON.Feature} feature - The feature cluster to expand.
+         * @return {number}
+         */
+        getClusterExpansionZoom,
+
+        /**
+         * Returns the FeatureCollection from the cluster.
+         *
+         * @example
+         * const collection = await shapeSource.getClusterLeaves(clusterId, limit, offset);
+         *
+         * @param  {GeoJSON.Feature} feature - The feature cluster to expand.
+         * @param  {number} limit - The number of points to return.
+         * @param  {number} offset - The amount of points to skip (for pagination).
+         * @return {GeoJSON.FeatureCollection}
+         */
+        getClusterLeaves,
+
+        /**
+         * Returns the FeatureCollection from the cluster (on the next zoom level).
+         *
+         * @example
+         * const collection = await shapeSource.getClusterChildren(clusterId);
+         *
+         * @param  {GeoJSON.Feature} feature - The feature cluster to expand.
+         * @return {GeoJSON.FeatureCollection}
+         */
+        getClusterChildren,
+
+        setNativeProps,
+
+        _nativeRef: _nativeRef.current,
+      }));
+
+      const _nativeRef = useRef<MLRNShapeSourceRefType>(null);
+
+      const {
+        _runNativeCommand,
+        _runPendingNativeCommands,
+        _onAndroidCallback,
+      } = useNativeBridge(NATIVE_MODULE_NAME);
+
+      const _setNativeRef = (nativeRef: MLRNShapeSourceRefType): void => {
+        _nativeRef.current = nativeRef;
+        _runPendingNativeCommands(nativeRef);
+      };
+
+      async function features(
+        filter?: FilterExpression,
+      ): Promise<GeoJSON.FeatureCollection> {
+        const res: { data: string | GeoJSON.FeatureCollection } =
+          await _runNativeCommand("features", _nativeRef.current, [
+            getFilter(filter),
+          ]);
+
+        if (isAndroid()) {
+          return JSON.parse(res.data as string);
+        }
+
+        return res.data as GeoJSON.FeatureCollection;
+      }
+
+      async function getClusterExpansionZoom(
+        feature: GeoJSON.Feature,
+      ): Promise<number> {
+        const res: { data: number } = await _runNativeCommand(
+          "getClusterExpansionZoom",
+          _nativeRef.current,
+          [JSON.stringify(feature)],
+        );
+        return res.data;
+      }
+
+      async function getClusterLeaves(
+        feature: GeoJSON.Feature,
+        limit: number,
+        offset: number,
+      ): Promise<GeoJSON.FeatureCollection> {
+        const res: { data: string | GeoJSON.FeatureCollection } =
+          await _runNativeCommand("getClusterLeaves", _nativeRef.current, [
+            JSON.stringify(feature),
+            limit,
+            offset,
+          ]);
+
+        if (isAndroid()) {
+          return JSON.parse(res.data as string);
+        }
+
+        return res.data as GeoJSON.FeatureCollection;
+      }
+
+      async function getClusterChildren(
+        feature: GeoJSON.Feature,
+      ): Promise<GeoJSON.FeatureCollection> {
+        const res: { data: string | GeoJSON.FeatureCollection } =
+          await _runNativeCommand("getClusterChildren", _nativeRef.current, [
+            JSON.stringify(feature),
+          ]);
+
+        if (isAndroid()) {
+          return JSON.parse(res.data as string);
+        }
+
+        return res.data as GeoJSON.FeatureCollection;
+      }
+
+      function setNativeProps(nativeProps: NativeProps): void {
+        if (!_nativeRef.current) {
+          return;
+        }
+
+        const shallowProps = Object.assign({}, nativeProps);
+
+        // Adds support for Animated
+        if (shallowProps.shape && typeof shallowProps.shape !== "string") {
+          shallowProps.shape = JSON.stringify(shallowProps.shape);
+        }
+
+        _nativeRef.current.setNativeProps(shallowProps);
+      }
+
+      function _getShape(): string | undefined {
+        if (!props.shape) {
+          return undefined;
+        }
+        return toJSONString(props.shape);
+      }
+
+      const shapeProps = {
+        id: shapeId,
+        testID: props.testID,
+        url: props.url,
+        shape: _getShape(),
+        hitbox: props.hitbox,
+        hasPressListener: !!props.onPress,
+        onMapboxShapeSourcePress: props.onPress,
+        cluster: props.cluster ? 1 : 0,
+        clusterRadius: props.clusterRadius,
+        clusterMinPoints: props.clusterMinPoints,
+        clusterMaxZoomLevel: props.clusterMaxZoomLevel,
+        clusterProperties: props.clusterProperties,
+        maxZoomLevel: props.maxZoomLevel,
+        buffer: props.buffer,
+        tolerance: props.tolerance,
+        lineMetrics: props.lineMetrics,
+        onPress: undefined,
+        ref: _setNativeRef,
+        onAndroidCallback: isAndroid() ? _onAndroidCallback : undefined,
+      };
+
+      return (
+        <MLRNShapeSource {...shapeProps}>
+          {cloneReactChildrenWithProps(props.children, {
+            sourceID: shapeId,
+          })}
+        </MLRNShapeSource>
+      );
+    },
+  ),
+);
+
+const MLRNShapeSource = requireNativeComponent<NativeProps>(NATIVE_MODULE_NAME);

package/src/components/sources/VectorSource.tsx

@@ -0,0 +1,172 @@
+import { featureCollection } from "@turf/helpers";
+import { forwardRef, memo, type ReactNode, useImperativeHandle } from "react";
+import {
+  NativeModules,
+  type NativeSyntheticEvent,
+  requireNativeComponent,
+} from "react-native";
+
+import { useAbstractSource } from "../../hooks/useAbstractSource";
+import { useNativeBridge } from "../../hooks/useNativeBridge";
+import { type BaseProps } from "../../types/BaseProps";
+import { type FilterExpression } from "../../types/MapLibreRNStyles";
+import { type PressEventWithFeatures } from "../../types/PressEvent";
+import { cloneReactChildrenWithProps, isAndroid } from "../../utils";
+import { getFilter } from "../../utils/filterUtils";
+
+const MLRNModule = NativeModules.MLRNModule;
+
+export const NATIVE_MODULE_NAME = "MLRNVectorSource";
+
+interface VectorSourceProps extends BaseProps {
+  /**
+   * A string that uniquely identifies the source.
+   */
+  id: string;
+  /**
+   * A URL to a TileJSON configuration file describing the source’s contents and other metadata.
+   */
+  url?: string;
+  /**
+   * 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
+   */
+  tileUrlTemplates?: string[];
+  /**
+   * An unsigned integer that specifies the minimum zoom level at which to display tiles from the source.
+   * The value should be between 0 and 22, inclusive, and less than
+   * maxZoomLevel, if specified. The default value for this option is 0.
+   */
+  minZoomLevel?: number;
+  /**
+   * An unsigned integer that specifies the maximum zoom level at which to display tiles from the source.
+   * The value should be between 0 and 22, inclusive, and less than
+   * minZoomLevel, if specified. The default value for this option is 22.
+   */
+  maxZoomLevel?: number;
+  /**
+   * Influences the y direction of the tile coordinates. (tms inverts y axis)
+   */
+  tms?: boolean;
+  /**
+   * An HTML or literal text string defining the buttons to be displayed in an action sheet when the
+   * source is part of a map view’s style and the map view’s attribution button is pressed.
+   */
+  attribution?: string;
+  /**
+   * Source press listener, gets called when a user presses one of the children layers only
+   * if that layer has a higher z-index than another source layers
+   */
+  onPress?: (event: NativeSyntheticEvent<PressEventWithFeatures>) => void;
+  /**
+   * Overrides the default touch hitbox(44x44 pixels) for the source layers
+   */
+  hitbox?: {
+    /**
+     * `width` of hitbox
+     */
+    width: number;
+    /**
+     * `height` of hitbox
+     */
+    height: number;
+  };
+
+  children?: ReactNode;
+}
+
+type NativeProps = VectorSourceProps;
+
+const MLRNVectorSource =
+  requireNativeComponent<VectorSourceProps>(NATIVE_MODULE_NAME);
+
+/**
+ * VectorSource is a map content source that supplies tiled vector data in Mapbox Vector Tile format to be shown on the map.
+ * The location of and metadata about the tiles are defined either by an option dictionary or by an external file that conforms to the TileJSON specification.
+ */
+export const VectorSource = memo(
+  forwardRef(
+    (
+      {
+        id = MLRNModule.StyleSource.DefaultSourceID,
+        ...props
+      }: VectorSourceProps,
+      ref,
+    ) => {
+      // * exposes the methods of the function component so we don't break projects that depend on calling this methods
+      useImperativeHandle(ref, () => ({
+        /**
+         * 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 includes all currently-loaded vector tiles
+         * and GeoJSON source tiles. This function does not check tiles outside of the visible viewport.
+         *
+         * @example
+         * vectorSource.features(['id1', 'id2'])
+         *
+         * @param  {Array=} layerIDs - A set of strings that correspond to the names of layers defined in the current style. Only the features contained in these layers are included in the returned array.
+         * @param  {Array=} filter - an optional filter statement to filter the returned Features.
+         * @return {GeoJSON.FeatureCollection}
+         */
+        features,
+      }));
+
+      const {
+        _runNativeCommand,
+        //  _runPendingNativeCommands,
+        _onAndroidCallback,
+      } = useNativeBridge(NATIVE_MODULE_NAME);
+      const { setNativeRef, _nativeRef } = useAbstractSource<NativeProps>();
+
+      // const _setNativeRef = (
+      //   nativeRef: (Component<NativeProps> & Readonly<NativeMethods>) | null,
+      // ): void => {
+      //   if (nativeRef) {
+      //     setNativeRef(nativeRef);
+      //     _runPendingNativeCommands(nativeRef);
+      //   }
+      // };
+
+      const features = async (
+        layerIDs = [],
+        filter?: FilterExpression,
+      ): Promise<GeoJSON.FeatureCollection> => {
+        if (!_nativeRef) {
+          return featureCollection([]);
+        }
+        const res: { data: string | GeoJSON.FeatureCollection } =
+          await _runNativeCommand("features", _nativeRef, [
+            [[layerIDs, getFilter(filter)]],
+          ]);
+
+        if (isAndroid()) {
+          return JSON.parse(res?.data as string);
+        }
+
+        return res.data as GeoJSON.FeatureCollection;
+      };
+
+      const allProps = {
+        id,
+        url: props.url,
+        tileUrlTemplates: props.tileUrlTemplates,
+        minZoomLevel: props.minZoomLevel,
+        maxZoomLevel: props.maxZoomLevel,
+        tms: props.tms,
+        attribution: props.attribution,
+        hitbox: props.hitbox,
+        hasPressListener: !!props.onPress,
+        onMapboxVectorSourcePress: props.onPress,
+        onPress: undefined,
+        onAndroidCallback: isAndroid() ? _onAndroidCallback : undefined,
+      };
+
+      return (
+        <MLRNVectorSource ref={setNativeRef} {...allProps}>
+          {cloneReactChildrenWithProps(props.children, {
+            sourceID: id,
+          })}
+        </MLRNVectorSource>
+      );
+    },
+  ),
+);

package/src/components/user-location/NativeUserLocation.tsx

@@ -0,0 +1,28 @@
+import UserLocationNativeComponent from "./UserLocationNativeComponent";
+import type { BaseProps } from "../../types/BaseProps";
+
+interface NativeUserLocationProps extends BaseProps {
+  /**
+   * Rendering mode
+   *
+   *  - "default": Renders only a puck
+   *  - "heading": Renders a puck with triangle indicating device heading based on compass
+   *  - "course": Android renders an arrow indicating device heading based on GPS course, iOS behaves like mode="heading"
+   *
+   * @default "default"
+   */
+  mode?: "default" | "heading" | "course";
+
+  /**
+   * Limit the maximum frames per second for location updates on Android
+   *
+   * Use this setting to limit animation rate of the location puck to decrease the stress on the device's CPU which could improve battery life.
+   *
+   * @platform android
+   */
+  androidPreferredFramesPerSecond?: number;
+}
+
+export const NativeUserLocation = (props: NativeUserLocationProps) => {
+  return <UserLocationNativeComponent {...props} />;
+};

package/src/components/user-location/UserLocation.tsx

@@ -0,0 +1,86 @@
+import { memo, type ReactNode, useMemo } from "react";
+
+import { UserLocationPuck } from "./UserLocationPuck";
+import { useCurrentPosition } from "../../hooks/useCurrentPosition";
+import { Annotation } from "../annotations/Annotation";
+
+export interface UserLocationProps {
+  /**
+   * Children to render inside the UserLocation Annotation, e.g. CircleLayer, SymbolLayer
+   */
+  children?: ReactNode;
+
+  /**
+   * Whether the UserLocation Annotation is animated between updates
+   */
+  animated?: boolean;
+
+  /**
+   * Render a circle which indicates the accuracy of the location
+   */
+  accuracy?: boolean;
+
+  /**
+   * Render an arrow which indicates direction the device is pointing relative to north
+   */
+  heading?: boolean;
+
+  /**
+   * Minimum delta in meters for location updates
+   */
+  minDisplacement?: number;
+
+  /**
+   * Event triggered on pressing the UserLocation Annotation
+   */
+  onPress?: () => void;
+}
+
+export const UserLocation = memo(
+  ({
+    animated = true,
+    accuracy = false,
+    heading = false,
+    minDisplacement,
+    children,
+    onPress,
+  }: UserLocationProps) => {
+    const currentPosition = useCurrentPosition({ minDisplacement });
+
+    const coordinates = useMemo(() => {
+      return currentPosition?.coords
+        ? [currentPosition.coords.longitude, currentPosition.coords.latitude]
+        : undefined;
+    }, [currentPosition?.coords]);
+
+    if (!coordinates || !currentPosition) {
+      return null;
+    }
+
+    return (
+      <Annotation
+        animated={animated}
+        id="mlrn-user-location"
+        testID="mlrn-user-location"
+        onPress={onPress}
+        coordinates={coordinates}
+        style={{
+          iconRotate: currentPosition.coords.heading ?? undefined,
+        }}
+      >
+        {children || (
+          <UserLocationPuck
+            testID="mlrn-user-location-puck"
+            sourceID="mlrn-user-location"
+            accuracy={accuracy ? currentPosition.coords.accuracy : undefined}
+            heading={
+              heading
+                ? (currentPosition.coords.heading ?? undefined)
+                : undefined
+            }
+          />
+        )}
+      </Annotation>
+    );
+  },
+);

package/src/components/user-location/UserLocationNativeComponent.ts

@@ -0,0 +1,19 @@
+import {
+  codegenNativeComponent,
+  type CodegenTypes,
+  type HostComponent,
+  type ViewProps,
+} from "react-native";
+
+export interface NativeProps extends ViewProps {
+  mode?: CodegenTypes.WithDefault<"default" | "heading" | "course", "default">;
+
+  androidPreferredFramesPerSecond?: CodegenTypes.WithDefault<
+    CodegenTypes.Int32,
+    -1
+  >;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  "MLRNNativeUserLocation",
+) as HostComponent<NativeProps>;