@mapvina-com/mapvina-react-native 1.0.0

package/src/components/sources/raster-dem-source/RasterDEMSourceNativeComponent.ts

@@ -0,0 +1,25 @@
+import {
+  codegenNativeComponent,
+  type CodegenTypes,
+  type HostComponent,
+  type ViewProps,
+} from "react-native";
+
+type NativeDEMEncoding = "mapbox" | "terrarium";
+
+export interface NativeProps extends ViewProps {
+  id: string;
+  url?: string;
+  tiles?: string[];
+
+  tileSize?: CodegenTypes.WithDefault<CodegenTypes.Int32, 512>;
+  minzoom?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>;
+  maxzoom?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>;
+  attribution?: string;
+
+  encoding?: CodegenTypes.WithDefault<NativeDEMEncoding, "mapbox">;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  "MLRNRasterDEMSource",
+) as HostComponent<NativeProps>;

package/src/components/sources/raster-source/RasterSource.tsx

@@ -0,0 +1,82 @@
+import { memo, type ReactNode } from "react";
+
+import RasterSourceNativeComponent from "./RasterSourceNativeComponent";
+import { useFrozenId } from "../../../hooks/useFrozenId";
+import { type BaseProps } from "../../../types/BaseProps";
+import { cloneReactChildrenWithProps } from "../../../utils";
+
+export interface RasterSourceProps 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/raster-tiles/{z}/{x}/{y}.png"
+   */
+  tiles?: 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 maxzoom, if specified. The default value for this option is 0.
+   */
+  minzoom?: 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 minzoom, if specified. The default value for this option is 22.
+   */
+  maxzoom?: number;
+
+  /**
+   * Size of the map tiles.
+   *
+   * @defaultValue 512
+   */
+  tileSize?: number;
+
+  /**
+   * Influences the y direction of the tile coordinates. (tms inverts y-axis)
+   *
+   * @defaultValue "xyz"
+   */
+  scheme?: "xyz" | "tms";
+
+  /**
+   * 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;
+
+  children?: ReactNode;
+}
+
+/**
+ * RasterSource is a map content source that supplies raster image tiles 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 RasterSource = memo(({ id, ...props }: RasterSourceProps) => {
+  const frozenId = useFrozenId(id);
+
+  return (
+    <RasterSourceNativeComponent id={frozenId} {...props}>
+      {cloneReactChildrenWithProps(props.children, {
+        source: frozenId,
+      })}
+    </RasterSourceNativeComponent>
+  );
+});

package/src/components/sources/raster-source/RasterSourceNativeComponent.ts

@@ -0,0 +1,25 @@
+import {
+  codegenNativeComponent,
+  type CodegenTypes,
+  type HostComponent,
+  type ViewProps,
+} from "react-native";
+
+type NativeScheme = "xyz" | "tms";
+
+export interface NativeProps extends ViewProps {
+  id: string;
+  url?: string;
+  tiles?: string[];
+
+  tileSize?: CodegenTypes.WithDefault<CodegenTypes.Int32, 512>;
+  minzoom?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>;
+  maxzoom?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>;
+  attribution?: string;
+
+  scheme?: CodegenTypes.WithDefault<NativeScheme, "xyz">;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  "MLRNRasterSource",
+) as HostComponent<NativeProps>;

package/src/components/sources/vector-source/NativeVectorSourceModule.ts

@@ -0,0 +1,15 @@
+import {
+  type CodegenTypes,
+  type TurboModule,
+  TurboModuleRegistry,
+} from "react-native";
+
+export interface Spec extends TurboModule {
+  querySourceFeatures: (
+    reactTag: CodegenTypes.Int32,
+    sourceLayer: string,
+    filter: string[],
+  ) => Promise<GeoJSON.Feature[]>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("MLRNVectorSourceModule");

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

@@ -0,0 +1,137 @@
+import type { FilterSpecification } from "@mapvina/mapvina-gl-style-spec";
+import {
+  Component,
+  type ComponentProps,
+  memo,
+  type ReactNode,
+  type Ref,
+  useImperativeHandle,
+  useRef,
+} from "react";
+import { type ReactNativeElement } from "react-native";
+
+import NativeVectorSourceModule from "./NativeVectorSourceModule";
+import VectorSourceNativeComponent from "./VectorSourceNativeComponent";
+import { useFrozenId } from "../../../hooks/useFrozenId";
+import { type BaseProps } from "../../../types/BaseProps";
+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
+   * 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 the visible viewport.
+   *
+   * @example
+   * ```ts
+   * vectorSource.querySourceFeatures({ sourceLayer: "some-source-layer" });
+   * ```
+   */
+  querySourceFeatures(options: {
+    sourceLayer: string;
+    filter?: FilterSpecification;
+  }): Promise<GeoJSON.Feature[]>;
+}
+
+export interface VectorSourceProps extends BaseProps, PressableSourceProps {
+  /**
+   * 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. Common format should be:
+   * `https://example.com/vector-tiles/{z}/{x}/{y}.pbf` .
+   */
+  tiles?: 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 maxzoom, if specified. The default value for this option is 0.
+   */
+  minzoom?: 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 minzoom, if specified. The default value for this option is 22.
+   */
+  maxzoom?: number;
+
+  /**
+   * Influences the y direction of the tile coordinates. (tms inverts y-axis)
+   *
+   * @defaultValue "xyz"
+   */
+  scheme?: "xyz" | "tms";
+
+  /**
+   * 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;
+
+  children?: ReactNode;
+
+  /**
+   * Ref to access VectorSource methods.
+   */
+  ref?: Ref<VectorSourceRef>;
+}
+
+/**
+ * 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(({ id, ref, ...props }: VectorSourceProps) => {
+  const nativeRef = useRef<
+    Component<ComponentProps<typeof VectorSourceNativeComponent>> &
+      ReactNativeElement
+  >(null);
+
+  const frozenId = useFrozenId(id);
+
+  useImperativeHandle(ref, () => ({
+    querySourceFeatures: async ({
+      sourceLayer,
+      filter,
+    }: {
+      sourceLayer: string;
+      filter?: FilterSpecification;
+    }): Promise<GeoJSON.Feature[]> => {
+      return NativeVectorSourceModule.querySourceFeatures(
+        findNodeHandle(nativeRef.current),
+        sourceLayer,
+        getNativeFilter(filter) as string[],
+      );
+    },
+  }));
+
+  return (
+    <VectorSourceNativeComponent
+      ref={nativeRef}
+      id={frozenId}
+      hasOnPress={!!props.onPress}
+      {...props}
+    >
+      {cloneReactChildrenWithProps(props.children, {
+        source: frozenId,
+      })}
+    </VectorSourceNativeComponent>
+  );
+});

package/src/components/sources/vector-source/VectorSourceNativeComponent.ts

@@ -0,0 +1,45 @@
+import {
+  codegenNativeComponent,
+  type CodegenTypes,
+  type HostComponent,
+  type ViewProps,
+} from "react-native";
+
+import type { UnsafeMixed } from "../../../types/codegen/UnsafeMixed";
+
+type NativeScheme = "xyz" | "tms";
+
+type NativeHitbox = {
+  top?: CodegenTypes.WithDefault<CodegenTypes.Int32, 0>;
+  right?: CodegenTypes.WithDefault<CodegenTypes.Int32, 0>;
+  bottom?: CodegenTypes.WithDefault<CodegenTypes.Int32, 0>;
+  left?: CodegenTypes.WithDefault<CodegenTypes.Int32, 0>;
+};
+
+type NativePressEvent = {
+  lngLat: UnsafeMixed<
+    [longitude: CodegenTypes.Double, latitude: CodegenTypes.Double]
+  >;
+  point: UnsafeMixed<[x: CodegenTypes.Double, y: CodegenTypes.Double]>;
+  features: UnsafeMixed<GeoJSON.Feature[]>;
+};
+
+export interface NativeProps extends ViewProps {
+  id: string;
+  url?: string;
+  tiles?: string[];
+
+  minzoom?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>;
+  maxzoom?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>;
+  scheme?: CodegenTypes.WithDefault<NativeScheme, "xyz">;
+  attribution?: string;
+
+  hitbox?: NativeHitbox;
+  hasOnPress: boolean;
+
+  onPress?: CodegenTypes.BubblingEventHandler<NativePressEvent>;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  "MLRNVectorSource",
+) as HostComponent<NativeProps>;

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

@@ -0,0 +1,31 @@
+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"
+   *
+   * @defaultValue "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,98 @@
+import { memo, type ReactNode, useMemo } from "react";
+
+import { UserLocationPuck } from "./UserLocationPuck";
+import headingIcon from "../../assets/heading.png";
+import { useCurrentPosition } from "../../hooks/useCurrentPosition";
+import type { LngLat } from "../../types/LngLat";
+import { LayerAnnotation } from "../annotations/LayerAnnotation";
+import { Images } from "../images/Images";
+
+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 lngLat: LngLat | undefined = useMemo(() => {
+      return currentPosition?.coords
+        ? [currentPosition.coords.longitude, currentPosition.coords.latitude]
+        : undefined;
+    }, [currentPosition?.coords]);
+
+    if (!lngLat || !currentPosition) {
+      return null;
+    }
+
+    return (
+      <>
+        {heading && (
+          <Images
+            images={{
+              "mlrn-user-location-puck-heading": headingIcon,
+            }}
+          />
+        )}
+
+        <LayerAnnotation
+          animated={animated}
+          id="mlrn-user-location"
+          testID="mlrn-user-location"
+          onPress={onPress}
+          lngLat={lngLat}
+        >
+          {children || (
+            <UserLocationPuck
+              testID="mlrn-user-location-puck"
+              source="mlrn-user-location"
+              accuracy={accuracy ? currentPosition.coords.accuracy : undefined}
+              heading={
+                heading
+                  ? (currentPosition.coords.heading ?? undefined)
+                  : undefined
+              }
+            />
+          )}
+        </LayerAnnotation>
+      </>
+    );
+  },
+);

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>;

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

@@ -0,0 +1,83 @@
+import type { CircleLayerSpecification } from "@mapvina/mapvina-gl-style-spec";
+import { memo } from "react";
+
+import type { BaseProps } from "../../types/BaseProps";
+import { Layer } from "../layer/Layer";
+import { UserLocationPuckHeading } from "./UserLocationPuckHeading";
+
+const blue = "#33B5E5";
+
+const CIRCLE_LAYERS_PAINT = {
+  accuracy: {
+    "circle-color": blue,
+    "circle-opacity": 0.2,
+    "circle-pitch-alignment": "map",
+  },
+  white: {
+    "circle-radius": 9,
+    "circle-color": "#fff",
+    "circle-pitch-alignment": "map",
+  },
+  blue: {
+    "circle-radius": 6,
+    "circle-color": blue,
+    "circle-pitch-alignment": "map",
+  },
+} as const satisfies Record<string, CircleLayerSpecification["paint"]>;
+
+interface UserLocationPuckProps extends BaseProps {
+  source: string;
+  accuracy?: number;
+  heading?: number;
+  beforeId?: string;
+}
+
+export const UserLocationPuck = memo(
+  ({ source, accuracy, heading }: UserLocationPuckProps) => {
+    return (
+      <>
+        {typeof accuracy === "number" && (
+          <Layer
+            type="circle"
+            id="mlrn-user-location-puck-accuracy"
+            testID="mlrn-user-location-puck-accuracy"
+            source={source}
+            paint={{
+              ...CIRCLE_LAYERS_PAINT.accuracy,
+              "circle-radius": [
+                "interpolate",
+                ["exponential", 2],
+                ["zoom"],
+                0,
+                CIRCLE_LAYERS_PAINT.white["circle-radius"],
+                22,
+                CIRCLE_LAYERS_PAINT.white["circle-radius"] + accuracy * 100,
+              ],
+            }}
+          />
+        )}
+        <Layer
+          type="circle"
+          id="mlrn-user-location-puck-white"
+          testID="mlrn-user-location-puck-white"
+          source={source}
+          paint={CIRCLE_LAYERS_PAINT.white}
+        />
+        <Layer
+          type="circle"
+          id="mlrn-user-location-puck-blue"
+          testID="mlrn-user-location-puck-blue"
+          source={source}
+          paint={CIRCLE_LAYERS_PAINT.blue}
+        />
+        {typeof heading === "number" && (
+          <UserLocationPuckHeading
+            source={source}
+            beforeId="mlrn-user-location-puck-white"
+            heading={heading}
+          />
+        )}
+      </>
+    );
+  },
+);

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

@@ -0,0 +1,34 @@
+import type { SymbolLayerSpecification } from "@mapvina/mapvina-gl-style-spec";
+import { memo } from "react";
+
+import { type BaseProps } from "../../types/BaseProps";
+import { Layer } from "../layer/Layer";
+
+const SYMBOL_LAYER_LAYOUT: SymbolLayerSpecification["layout"] = {
+  "icon-image": "mlrn-user-location-puck-heading",
+  "icon-allow-overlap": true,
+  "icon-pitch-alignment": "map",
+  "icon-rotation-alignment": "map",
+};
+
+interface UserLocationPuckHeadingProps extends BaseProps {
+  source: string;
+  beforeId?: string;
+  heading: number;
+}
+
+export const UserLocationPuckHeading = memo(
+  ({ source, beforeId, heading }: UserLocationPuckHeadingProps) => (
+    <Layer
+      type="symbol"
+      id="mlrn-user-location-puck-heading"
+      testID="mlrn-user-location-puck-heading"
+      source={source}
+      beforeId={beforeId}
+      layout={{
+        ...SYMBOL_LAYER_LAYOUT,
+        "icon-rotate": heading,
+      }}
+    />
+  ),
+);

package/src/hooks/useCurrentPosition.ts

@@ -0,0 +1,53 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  type GeolocationPosition,
+  LocationManager,
+} from "../modules/location/LocationManager";
+
+interface UseCurrentPositionOptions {
+  /**
+   * Enable or disable position updates
+   *
+   * @defaultValue true
+   */
+  enabled?: boolean;
+
+  /**
+   * Minimum displacement in meters to trigger position update
+   *
+   * @defaultValue 0
+   */
+  minDisplacement?: number;
+}
+
+export function useCurrentPosition({
+  enabled = true,
+  minDisplacement,
+}: UseCurrentPositionOptions = {}) {
+  const [currentPosition, setCurrentPosition] = useState<GeolocationPosition>();
+
+  useEffect(() => {
+    if (minDisplacement !== undefined) {
+      LocationManager.setMinDisplacement(minDisplacement);
+    }
+  }, [minDisplacement]);
+
+  const handleUpdate = useCallback((position: GeolocationPosition) => {
+    setCurrentPosition(position);
+  }, []);
+
+  useEffect(() => {
+    if (enabled) {
+      LocationManager.addListener(handleUpdate);
+    }
+
+    return () => {
+      if (enabled) {
+        LocationManager.removeListener(handleUpdate);
+      }
+    };
+  }, [enabled, handleUpdate]);
+
+  return currentPosition;
+}

package/src/hooks/useFrozenId.ts

@@ -0,0 +1,13 @@
+import { useState } from "react";
+
+let generatedIdCounter = 0;
+
+export function useFrozenId(id?: string) {
+  const [frozenId] = useState(id ? id : `mlrn-${generatedIdCounter++}`);
+
+  if (id && id !== frozenId) {
+    throw new Error("`id` cannot be changed");
+  }
+
+  return frozenId;
+}