@mapvina-com/mapvina-react-native 1.0.0

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

@@ -0,0 +1,304 @@
+import NativeTransformRequestModule from "./NativeTransformRequestModule";
+
+export interface TransformOptions {
+  /**
+   * The id is used to identify a transform. Can be used to remove or update it.
+   * When omitted it will be auto-generated.
+   */
+  id?: string;
+
+  /**
+   * Optional regex to be used as the condition, if the transform should be
+   * applied. When omitted the transform will always be applied.
+   *
+   * Global flags are (like `/i` ) are not supported. Supports only inline flags,
+   * e.g. `(?i)` for case-insensitive matching.
+   */
+  match?: RegExp | string;
+}
+
+/**
+ * A serializable transform for rewriting MapVina request URLs.
+ *
+ * Transforms are applied as a pipeline in the order they were added: transform
+ * N+1 sees the URL *after* transform N has possibly changed it.
+ */
+export interface UrlTransformOptions extends TransformOptions {
+  /**
+   * Regex to find the portion of the URL to replace. Supports capture groups that
+   * can be back-referenced in `replace` as `$1` , `$2` , …
+   *
+   * Global flags are (like `/i` ) are not supported. Supports only inline flags,
+   * e.g. `(?i)` for case-insensitive matching.
+   */
+  find: RegExp | string;
+
+  /**
+   * Replacement string. Reference capture groups from `find` with `$1`, `$2`, …
+   */
+  replace: string;
+}
+
+/**
+ * A URL query parameter to append to matching map resource requests.
+ */
+export interface UrlSearchParamOptions extends TransformOptions {
+  /** The query parameter name (e.g., `"apiKey"`). */
+  name: string;
+
+  /** The query parameter value (e.g., your API key). */
+  value: string;
+}
+
+/**
+ * A HTTP header to send with matching map resource requests.
+ */
+export interface HeaderOptions extends TransformOptions {
+  /** The header name (e.g., `"Authorization"`). */
+  name: string;
+
+  /** The header value (e.g., `"Bearer token123"`). */
+  value: string;
+}
+
+/**
+ * TransformRequestManager provides methods for managing HTTP requests made by
+ * MapVina.
+ *
+ * Transformations are possible in three ways:
+ *
+ * - Transforming the URL with search and replace
+ * - Adding URL search params
+ * - Adding HTTP headers
+ *
+ * Transforms are applied in this order. The `match` conditions are applied to
+ * possibly already transformed URLs.
+ *
+ * To gain insight into which transforms are applied set the log level to
+ * `"debug"` via {@link LogManager}:
+ *
+ * ```ts
+ * LogManager.setLogLevel("debug");
+ * ```
+ */
+class TransformRequestManager {
+  /**
+   * Adds or updates a URL transform identified by `id`.
+   *
+   * Transforms execute in insertion order. Therefore `match` and `find` regexes
+   * are matched against possibly already modified URL by previous transforms.
+   *
+   * Re-adding an existing `id` updates the transform **in-place**, preserving its
+   * position in the pipeline. This makes it safe to refresh tokens or swap
+   * domains without disrupting the order of other transforms.
+   *
+   * URL transforms are applied before `addUrlSearchParam` and `addHeader`.
+   *
+   * @param options - The transform. Set {@link TransformOptions.id} to a stable string to enable
+   *   in-place updates; if omitted an id is auto-generated and returned.
+   * @returns The id of the transform (the value of `transform.id` when provided, otherwise the auto-generated one). Pass it to {@link removeUrlTransform} to remove it later.
+   *
+   * @example Upgrade all requests to HTTPS
+   * ```ts
+   * TransformRequestManager.addUrlTransform({
+   *   id: "force-https",
+   *   find: "^http://",
+   *   replace: "https://",
+   * });
+   * ```
+   *
+   * @example Redirect a specific domain through a proxy
+   * ```ts
+   * TransformRequestManager.addUrlTransform({
+   *   id: "proxy",
+   *   match: "tiles\\.example\\.com",
+   *   find: "tiles\\.example\\.com",
+   *   replace: "proxy.example.com",
+   * });
+   * ```
+   *
+   * @example Inject an API key into the path using a capture group
+   * ```ts
+   * TransformRequestManager.addUrlTransform({
+   *   id: "api-key",
+   *   match: "api\\.example\\.com",
+   *   find: "(https://api\\.example\\.com/)(.*)",
+   *   replace: "$1mySecretKey/$2",
+   * });
+   * ```
+   */
+  addUrlTransform(options: UrlTransformOptions): string {
+    const id = options.id ?? this.getId();
+
+    NativeTransformRequestModule.addUrlTransform(
+      id,
+      TransformRequestManager.toRegexString(options.match),
+      TransformRequestManager.toRegexString(options.find) ?? "",
+      options.replace,
+    );
+
+    return id;
+  }
+
+  /**
+   * Removes the URL transform with the given `id` . No-op if the id is not
+   * registered.
+   *
+   * @param id - The identifier passed to/returned from {@link addUrlTransform}.
+   */
+  removeUrlTransform(id: string): void {
+    NativeTransformRequestModule.removeUrlTransform(id);
+  }
+
+  /**
+   * Removes all registered URL transforms
+   */
+  clearUrlTransforms(): void {
+    NativeTransformRequestModule.clearUrlTransforms();
+  }
+
+  /**
+   * Adds or updates a URL query parameter identified by `id` that will be
+   * appended to all matching map resource requests. Re-adding an existing `id`
+   *  updates the param in-place.
+   *
+   * @param options - The options. Set {@link TransformOptions.id} to a stable string to enable
+   *   in-place updates; if omitted an id is auto-generated and returned.
+   * @returns The id of the options. Pass it to {@link removeUrlSearchParam} to remove it later.
+   *
+   * @example Add apiKey to for a specific domain
+   * ```ts
+   * TransformRequestManager.addUrlSearchParam({
+   *   match: /tiles\.example\.com/,
+   *   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();
+
+    NativeTransformRequestModule.addUrlSearchParam(
+      id,
+      TransformRequestManager.toRegexString(options.match),
+      options.name,
+      options.value,
+    );
+
+    return id;
+  }
+
+  /**
+   * Removes a previously added URL query parameter by its `id`.
+   *
+   * @param id - The identifier passed to/returned from {@link addUrlSearchParam}.
+   */
+  removeUrlSearchParam(id: string): void {
+    NativeTransformRequestModule.removeUrlSearchParam(id);
+  }
+
+  /**
+   * Adds or updates an HTTP header identified by `id` that will be sent with all
+   * matching map resource requests. Re-adding an existing `id` updates the header
+   * in-place.
+   *
+   * @param options - The options. Set {@link TransformOptions.id} to a stable string to enable
+   *   in-place updates; if omitted an id is auto-generated and returned.
+   * @returns The id of the options. Pass it to {@link removeHeader} to remove it later.
+   *
+   * @example Add header to all requests
+   * ```
+   * TransformRequestManager.addHeader({ name: "Authorization", value: "Bearer token123" });
+   * ```
+   *
+   * @example Add header only to requests matching a pattern
+   * ```ts
+   * TransformRequestManager.addHeader({
+   *   name: "X-API-Key",
+   *   value: "key123",
+   *   match: /https:\/\/api\.example\.com\/tiles\//,
+   * });
+   * ```
+   */
+  addHeader(options: HeaderOptions): string {
+    const id = options.id ?? this.getId();
+
+    NativeTransformRequestModule.addHeader(
+      id,
+      TransformRequestManager.toRegexString(options.match),
+      options.name,
+      options.value,
+    );
+
+    return id;
+  }
+
+  /**
+   * Removes all registered URL search params.
+   */
+  clearUrlSearchParams(): void {
+    NativeTransformRequestModule.clearUrlSearchParams();
+  }
+
+  /**
+   * Removes a previously added HTTP header by its `id`.
+   *
+   * @param id - The identifier passed to/returned from {@link addHeader}.
+   */
+  removeHeader(id: string): void {
+    NativeTransformRequestModule.removeHeader(id);
+  }
+
+  /**
+   * Removes all registered HTTP headers.
+   */
+  clearHeaders(): void {
+    NativeTransformRequestModule.clearHeaders();
+  }
+
+  /**
+   * Removes all registered URL transforms, URL search params and HTTP headers.
+   */
+  clear(): void {
+    this.clearUrlTransforms();
+    this.clearUrlSearchParams();
+    this.clearHeaders();
+  }
+
+  private lastId: number = -1;
+
+  private getId() {
+    this.lastId++;
+
+    return "transform-request-" + this.lastId;
+  }
+
+  private static toRegexString(
+    value: string | RegExp | undefined,
+  ): string | null {
+    let result: string | undefined = undefined;
+    if (value instanceof RegExp) {
+      if (value.flags) {
+        throw new Error("Regex flags are not supported");
+      }
+
+      result = value.source;
+    } else {
+      result = value;
+    }
+
+    return result || null;
+  }
+}
+
+const transformRequestManager = new TransformRequestManager();
+
+export { transformRequestManager as TransformRequestManager };

package/src/plugin/MapVinaPluginProps.ts

@@ -0,0 +1,84 @@
+type VersionString =
+  | `${number}.${number}.${number}`
+  | `${number}.${number}.${number}-${string}`;
+
+export type MapVinaPluginProps =
+  | {
+      /**
+       * Properties relevant only for Android
+       *
+       * @platform Android
+       */
+      android?: {
+        /**
+         * Version for `io.github.mapvina.gl:android-sdk-*`
+         */
+        nativeVersion?: VersionString;
+        /**
+         * Variant of `io.github.mapvina.gl:android-sdk-*`
+         *
+         * @defaultValue "opengl"
+         */
+        nativeVariant?: "opengl" | "vulkan";
+        /**
+         * Version for `io.github.mapvina.gl:android-plugin-*-v9`
+         */
+        pluginVersion?: VersionString;
+        /**
+         * Version for `io.github.mapvina.gl:android-sdk-turf`
+         */
+        turfVersion?: VersionString;
+        /**
+         * Version for `com.squareup.okhttp3:okhttp`
+         */
+        okhttpVersion?: VersionString;
+
+        /**
+         * Location engine to be used
+         *
+         * - `default`: Used per default from MapVina; F-Droid compatible
+         * - `google`: Google Play Services Location Engine for higher precision; F-Droid
+         *   incompatible
+         *
+         * @defaultValue "default"
+         */
+        locationEngine?: "default" | "google";
+        /**
+         * Version for `com.google.android.gms:play-services-location` , only used with
+         * `locationEngine: "google"`
+         */
+        googlePlayServicesLocationVersion?: VersionString;
+      };
+
+      /**
+       * Properties relevant only for iOS
+       *
+       * @platform iOS
+       */
+      ios?: {
+        /**
+         * Version for `mapvina-gl-native-distribution`
+         */
+        nativeVersion?: VersionString;
+
+        /**
+         * Swift Package Manager spec to override the selected version range
+         *
+         * @defaultValue `{ url: "https://github.io/github/mapvina/mapvina-gl-native-distribution", requirement: { kind: "exactVersion", version: $MLRN_NATIVE_VERSION }, product_name: "MapVina" }`
+         *
+         * @example
+         * ```ts
+         * spmSpec: `{
+         *   url: "https://github.io/github/mapvina/mapvina-gl-native-distribution",
+         *   requirement: {
+         *     kind: "upToNextMajorVersion",
+         *     minimumVersion: "x.x.x"
+         *   },
+         *   product_name: "MapVina"
+         * }`;
+         * ```
+         */
+        spmSpec?: string;
+      };
+    }
+  | undefined;

package/src/plugin/android.ts

@@ -0,0 +1,68 @@
+import {
+  type ConfigPlugin,
+  withGradleProperties as withGradlePropertiesExpo,
+} from "@expo/config-plugins";
+import type { PropertiesItem } from "@expo/config-plugins/build/android/Properties";
+
+import type { MapVinaPluginProps } from "./MapVinaPluginProps";
+
+type PropertyItem = {
+  type: "property";
+  key: string;
+  value: string;
+};
+
+export const GRADLE_PROPERTIES_PREFIX = "io.github.mapvina.reactnative.";
+
+export const getGradleProperties = (
+  props: MapVinaPluginProps,
+): PropertyItem[] => {
+  return Object.entries(props?.android || {}).reduce(
+    (properties, [key, value]) => {
+      if (key && value) {
+        properties.push({
+          type: "property",
+          key: `${GRADLE_PROPERTIES_PREFIX}${key}`,
+          value: value.toString(),
+        });
+      }
+
+      return properties;
+    },
+    [] as PropertyItem[],
+  );
+};
+
+export const mergeGradleProperties = (
+  oldProperties: PropertiesItem[],
+  newProperties: PropertyItem[],
+): PropertiesItem[] => {
+  const merged = oldProperties.filter(
+    (item) =>
+      !(
+        item.type === "property" &&
+        item.key.startsWith(GRADLE_PROPERTIES_PREFIX)
+      ),
+  );
+
+  merged.push(...newProperties);
+
+  return merged;
+};
+
+export const withGradleProperties: ConfigPlugin<MapVinaPluginProps> = (
+  config,
+  props,
+) => {
+  const gradleProperties = getGradleProperties(props);
+
+  return withGradlePropertiesExpo(config, (c) => {
+    c.modResults = mergeGradleProperties(c.modResults, gradleProperties);
+
+    return c;
+  });
+};
+
+export const android = {
+  withGradleProperties,
+};

package/src/plugin/ios.ts

@@ -0,0 +1,114 @@
+import {
+  type ConfigPlugin,
+  withPodfile,
+  withXcodeProject,
+} from "@expo/config-plugins";
+import {
+  mergeContents,
+  removeGeneratedContents,
+} from "@expo/config-plugins/build/utils/generateCode";
+
+import type { MapVinaPluginProps } from "./MapVinaPluginProps";
+
+const TAG_PREFIX = `@mapvina/mapvina-react-native`;
+
+/**
+ * Only the post-install block is required, the post installer block is used for
+ * SPM (Swift Package Manager) which Expo doesn't currently support.
+ */
+export function applyPodfilePostInstall(contents: string): string {
+  const result = mergeContents({
+    tag: `${TAG_PREFIX}:post-install`,
+    src: contents,
+    newSrc: `    $MLRN.post_install(installer)`,
+    anchor: /post_install do \|installer\|/,
+    offset: 1,
+    comment: "#",
+  });
+
+  if (result.didMerge || result.didClear) {
+    return result.contents;
+  }
+
+  return contents;
+}
+
+const withPodfilePostInstall: ConfigPlugin = (config) => {
+  return withPodfile(config, (c) => {
+    c.modResults.contents = applyPodfilePostInstall(c.modResults.contents);
+
+    return c;
+  });
+};
+
+export const applyPodfileGlobalVariables = (
+  contents: string,
+  props: MapVinaPluginProps,
+): string => {
+  const tag = `${TAG_PREFIX}:global-variables`;
+
+  const globalVariables = [];
+
+  if (props?.ios?.nativeVersion) {
+    globalVariables.push(`$MLRN_NATIVE_VERSION = "${props.ios.nativeVersion}"`);
+  }
+
+  if (props?.ios?.spmSpec) {
+    globalVariables.push(`$MLRN_SPM_SPEC = ${props.ios.spmSpec}`);
+  }
+
+  if (globalVariables.length > 0) {
+    return mergeContents({
+      tag,
+      src: contents,
+      newSrc: globalVariables.join("\n"),
+      anchor: /target .+ do/,
+      offset: 0,
+      comment: "#",
+    }).contents;
+  }
+
+  const modified = removeGeneratedContents(contents, tag);
+
+  return modified ?? contents;
+};
+
+export const withPodfileGlobalVariables: ConfigPlugin<MapVinaPluginProps> = (
+  config,
+  props,
+) => {
+  return withPodfile(config, (c) => {
+    c.modResults.contents = applyPodfileGlobalVariables(
+      c.modResults.contents,
+      props,
+    );
+
+    return c;
+  });
+};
+
+/**
+ * Set the Debug Information Format to DWARF with dSYM File during EAS Build for
+ * Managed App https://github.com/expo/eas-cli/issues/968
+ *
+ * Set `artifactPath` in `eas.json`:
+ *
+ * ```json
+ * "ios": {
+ *    "artifactPath": "ios/build/*"
+ *  }
+ * ```
+ */
+const withDwarfDsym: ConfigPlugin = (config) => {
+  return withXcodeProject(config, (c) => {
+    c.modResults.debugInformationFormat = "dwarf-with-dsym";
+
+    return c;
+  });
+};
+
+export const ios = {
+  withPodfilePostInstall,
+  withPodfileGlobalVariables,
+  withDwarfDsym,
+};

package/src/types/Anchor.ts

@@ -0,0 +1,43 @@
+/**
+ * Position anchor for markers and annotations. Follows MapVina GL JS
+ * PositionAnchor format.
+ *
+ * @see {@link https://mapvina.io/github/mapvina-gl-js/docs/API/type-aliases/PositionAnchor/}
+ */
+export type Anchor =
+  | "center"
+  | "top"
+  | "bottom"
+  | "left"
+  | "right"
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right";
+
+/**
+ * Converts an Anchor string to native {x, y} format. x: 0 = left, 0.5 = center,
+ * 1 = right y: 0 = top, 0.5 = center, 1 = bottom
+ */
+export function anchorToNative(anchor: Anchor): { x: number; y: number } {
+  switch (anchor) {
+    case "center":
+      return { x: 0.5, y: 0.5 };
+    case "top":
+      return { x: 0.5, y: 0 };
+    case "bottom":
+      return { x: 0.5, y: 1 };
+    case "left":
+      return { x: 0, y: 0.5 };
+    case "right":
+      return { x: 1, y: 0.5 };
+    case "top-left":
+      return { x: 0, y: 0 };
+    case "top-right":
+      return { x: 1, y: 0 };
+    case "bottom-left":
+      return { x: 0, y: 1 };
+    case "bottom-right":
+      return { x: 1, y: 1 };
+  }
+}

package/src/types/BaseProps.ts

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

package/src/types/LngLat.ts

@@ -0,0 +1,4 @@
+/**
+ * Geographic coordinates
+ */
+export type LngLat = [longitude: number, latitude: number];

package/src/types/LngLatBounds.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents bounds in geographic coordinates
+ *
+ * Uses order of south-west and north-east corners in flat style per GeoJSON
+ * RFC.
+ */
+export type LngLatBounds = [
+  west: number,
+  south: number,
+  east: number,
+  north: number,
+];