@maydon_tech/react-native-nitro-maps 0.1.0

package/src/types/marker.ts

@@ -0,0 +1,267 @@
+import type { Coordinate, Point } from './map';
+import type { ColorValue } from '../utils/colors';
+
+/**
+ * Visual style of the marker
+ * - `'default'` - Standard Google Maps marker
+ * - `'price'` - Simple price tag
+ * - `'image'` - Custom image marker
+ * - `'priceMarker'` - Full-featured price marker with currency
+ * - `'reactView'` - React Native view marker (internal use by NitroCustomMarker)
+ *
+ * Note: For React Native views as markers, use the NitroCustomMarker component.
+ */
+export type MarkerStyle = 'default' | 'image' | 'priceMarker';
+
+/**
+ * Animation type for individual markers when they appear
+ * - `'none'` - No animation
+ * - `'pop'` - Pop/bounce effect
+ * - `'fadeIn'` - Fade in animation
+ */
+export type MarkerAnimation = 'none' | 'pop' | 'fadeIn';
+
+/**
+ * Animation style for cluster expand/collapse
+ * - `'default'` - Standard Google Maps Utils animation
+ * - `'bounce'` - Markers bounce when appearing
+ * - `'scale'` - Scale up from 0 to full size
+ * - `'fade'` - Fade in/out
+ * - `'spring'` - Spring effect animation
+ */
+export type ClusterAnimationStyle =
+  | 'default'
+  | 'bounce'
+  | 'scale'
+  | 'fade'
+  | 'spring';
+
+/**
+ * Style configuration for price markers
+ * Colors can be hex strings ("#FF0000", "#F00") or MarkerColor objects
+ */
+export type PriceMarkerStyle = {
+  /** Price text to display (e.g., "9M", "150K") */
+  price: string;
+  /** Currency code (e.g., "UZS", "USD", "EUR") */
+  currency: string;
+  /** Whether the marker is in selected state (changes colors) */
+  selected: boolean;
+  /** Background color in normal state (hex string or MarkerColor) */
+  backgroundColor?: ColorValue;
+  /** Background color when selected (hex string or MarkerColor) */
+  selectedBackgroundColor?: ColorValue;
+  /** Text color in normal state (hex string or MarkerColor) */
+  textColor?: ColorValue;
+  /** Text color when selected (hex string or MarkerColor) */
+  selectedTextColor?: ColorValue;
+  /** Font size in pixels */
+  fontSize?: number;
+  /** Horizontal padding in pixels */
+  paddingHorizontal?: number;
+  /** Vertical padding in pixels */
+  paddingVertical?: number;
+  /** Shadow opacity (0-1) */
+  shadowOpacity?: number;
+};
+
+/**
+ * RGBA color representation
+ * All values range from 0-255
+ */
+export type MarkerColor = {
+  /** Red component (0-255) */
+  r: number;
+  /** Green component (0-255) */
+  g: number;
+  /** Blue component (0-255) */
+  b: number;
+  /** Alpha/opacity component (0-255) */
+  a: number;
+};
+
+/**
+ * Configuration for price-style markers
+ */
+export type PriceMarkerConfig = {
+  /** Price text to display */
+  price: string;
+  /** Background color */
+  backgroundColor: MarkerColor;
+  /** Text color */
+  textColor: MarkerColor;
+  /** Font size in pixels */
+  fontSize: number;
+  /** Corner radius in pixels */
+  cornerRadius: number;
+  /** Whether marker is in selected state */
+  selected: boolean;
+};
+
+/**
+ * Configuration for image-style markers
+ * Colors can be hex strings ("#FF0000", "#F00") or MarkerColor objects
+ */
+export type ImageMarkerConfig = {
+  /** URL of the image to display */
+  imageUrl?: string;
+  /** Base64-encoded image data (alternative to URL) */
+  imageBase64?: string;
+  /** Image width in pixels */
+  width: number;
+  /** Image height in pixels */
+  height: number;
+  /** Corner radius in pixels */
+  cornerRadius: number;
+  /** Border thickness in pixels */
+  borderWidth: number;
+  /** Border color (hex string or MarkerColor) */
+  borderColor: ColorValue;
+};
+
+/**
+ * Combined marker configuration based on style type
+ */
+export type MarkerConfig = {
+  /** The marker style type */
+  style: MarkerStyle;
+  /** Image marker config (when style is 'image') */
+  image?: ImageMarkerConfig;
+  /** Price marker style config (when style is 'priceMarker') */
+  priceMarker?: PriceMarkerStyle;
+  /** React view marker config (when style is 'reactView') */
+};
+
+/**
+ * Complete marker data structure used internally
+ */
+export type MarkerData = {
+  /** Unique identifier for the marker */
+  id: string;
+  /** Geographic coordinates of the marker */
+  coordinate: Coordinate;
+  /** Title shown in info window */
+  title?: string;
+  /** Description shown in info window */
+  description?: string;
+  /** Whether the marker can be dragged */
+  draggable: boolean;
+  /** Marker opacity (0-1) */
+  opacity: number;
+  /** Rotation in degrees */
+  rotation: number;
+  /** Z-index for overlapping markers */
+  zIndex: number;
+  /** Anchor point for positioning (0-1 range) */
+  anchor: Point;
+  /** Visual configuration for the marker */
+  config: MarkerConfig;
+  /** Whether this marker should be included in clustering */
+  clusteringEnabled: boolean;
+  /** Animation when marker appears */
+  animation: MarkerAnimation;
+};
+
+/**
+ * Event data when a marker is pressed
+ */
+export type MarkerPressEvent = {
+  /** ID of the pressed marker */
+  id: string;
+  /** Coordinates where marker was pressed */
+  coordinate: Coordinate;
+};
+
+/**
+ * Event data during marker drag operations
+ */
+export type MarkerDragEvent = {
+  /** ID of the dragged marker */
+  id: string;
+  /** Current coordinates during drag */
+  coordinate: Coordinate;
+};
+
+/**
+ * Event data when a cluster is pressed
+ */
+export type ClusterPressEvent = {
+  /** Coordinates of the cluster */
+  coordinate: Coordinate;
+  /** IDs of all markers in the cluster */
+  markerIds: string[];
+  /** Number of markers in the cluster */
+  count: number;
+};
+
+/**
+ * Clustering strategy
+ * - `'supercluster'` - Pure geographic clustering. Overlapping icons are tolerated.
+ *   This is what Mapbox and most map libraries use. User zooms in to resolve overlaps.
+ * - `'hideOnOverlap'` - After geographic clustering, overlapping icons are hidden
+ *   (not merged). Every visible marker sits at its real geographic position.
+ *   This is what Zillow/Airbnb use for property maps.
+ */
+export type ClusterStrategy = 'supercluster' | 'hideOnOverlap';
+
+/**
+ * Configuration for marker clustering behavior
+ * Colors can be hex strings ("#FF0000", "#F00") or MarkerColor objects
+ */
+export type ClusterConfig = {
+  /** Enable or disable clustering */
+  enabled: boolean;
+  /**
+   * Clustering strategy
+   * - `'supercluster'` — overlaps tolerated, user zooms to resolve
+   * - `'hideOnOverlap'` — lower-priority overlapping icons hidden
+   * @default 'supercluster'
+   */
+  strategy: ClusterStrategy;
+  /**
+   * Clustering radius in pixels.
+   * Controls how aggressively markers group together.
+   * Higher = fewer, larger clusters. Lower = more, smaller clusters.
+   * @default 80
+   */
+  radius: number;
+  /** Minimum number of markers to form a cluster */
+  minimumClusterSize: number;
+  /** Maximum zoom level at which clustering occurs */
+  maxZoom: number;
+  /** Background color of cluster circles (hex string or MarkerColor) */
+  backgroundColor: ColorValue;
+  /** Text color for cluster count numbers (hex string or MarkerColor) */
+  textColor: ColorValue;
+  /** Border thickness in pixels */
+  borderWidth: number;
+  /** Border color of cluster circles (hex string or MarkerColor) */
+  borderColor: ColorValue;
+  /** Enable cluster animations */
+  animatesClusters: boolean;
+  /** Animation duration in seconds (e.g., 0.3) */
+  animationDuration: number;
+  /** Animation style for cluster expand/collapse */
+  animationStyle: ClusterAnimationStyle;
+  /**
+   * When true, clusters update live during pan/zoom gestures (throttled).
+   * When false, clusters only update after the gesture ends (debounced).
+   * Live mode provides smoother UX but uses more CPU.
+   * @default false
+   */
+  realtimeClustering: boolean;
+  /**
+   * Extra buffer around the visible viewport for pre-computing clusters.
+   * Expressed as a fraction of the viewport size (0 = no buffer, 0.5 = 50% extra on each side).
+   * Prevents markers from "popping in" at edges during pan.
+   * @default 0
+   */
+  renderBuffer: number;
+  /**
+   * Throttle interval in milliseconds for live clustering during gestures.
+   * Only used when `realtimeClustering` is true.
+   * Higher = better performance, lower = smoother updates.
+   * @default 150
+   */
+  throttleInterval: number;
+};

package/src/utils/colors.ts

@@ -0,0 +1,159 @@
+// ============ Color Helpers ============
+
+import type { MarkerColor } from '../types/marker';
+
+/**
+ * Color value that can be either a MarkerColor object or a hex string
+ * Hex strings can be in formats: "#RRGGBB", "RRGGBB", "#RGB", or "RGB"
+ * @example
+ * ```ts
+ * const color1: ColorValue = "#FF0000";        // Hex string
+ * const color2: ColorValue = "#F00";           // Short hex
+ * const color3: ColorValue = { r: 255, g: 0, b: 0, a: 255 }; // MarkerColor
+ * ```
+ */
+export type ColorValue = MarkerColor | string;
+
+/**
+ * Parse a ColorValue into a MarkerColor object
+ * Handles both hex strings and MarkerColor objects
+ * @param color - Color value (hex string or MarkerColor)
+ * @param defaultAlpha - Default alpha value (0-255) for hex strings
+ * @returns MarkerColor object
+ * @internal
+ */
+export const parseColor = (
+  color: ColorValue | undefined,
+  defaultAlpha: number = 255
+): MarkerColor | undefined => {
+  if (color === undefined) {
+    return undefined;
+  }
+
+  // If it's already a MarkerColor object, return as-is
+  if (
+    typeof color === 'object' &&
+    'r' in color &&
+    'g' in color &&
+    'b' in color
+  ) {
+    return {
+      r: color.r,
+      g: color.g,
+      b: color.b,
+      a: color.a ?? defaultAlpha,
+    };
+  }
+
+  // It's a string - parse as hex
+  if (typeof color === 'string') {
+    return hex(color, defaultAlpha);
+  }
+
+  return undefined;
+};
+
+/**
+ * Parse a ColorValue with a fallback default color
+ * @param color - Color value (hex string or MarkerColor)
+ * @param fallback - Fallback MarkerColor if parsing fails
+ * @returns MarkerColor object
+ * @internal
+ */
+export const parseColorWithFallback = (
+  color: ColorValue | undefined,
+  fallback: MarkerColor
+): MarkerColor => {
+  const parsed = parseColor(color);
+  return parsed ?? fallback;
+};
+
+/**
+ * Create a MarkerColor from RGB values
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @param a - Alpha/opacity (0-255, default: 255)
+ * @returns MarkerColor object
+ * @example
+ * ```ts
+ * const customRed = rgb(255, 0, 0);
+ * const semiTransparent = rgb(0, 0, 255, 128);
+ * ```
+ */
+export const rgb = (
+  r: number,
+  g: number,
+  b: number,
+  a: number = 255
+): MarkerColor => ({
+  r,
+  g,
+  b,
+  a,
+});
+
+/**
+ * Create a MarkerColor from a hex string
+ * @param hexStr - Hex color string (e.g., "#FF0000", "FF0000", "#F00", or "F00")
+ * @param alpha - Alpha/opacity (0-255, default: 255)
+ * @returns MarkerColor object
+ * @example
+ * ```ts
+ * const red = hex("#FF0000");
+ * const shortRed = hex("#F00");
+ * const semiTransparentBlue = hex("#0000FF", 128);
+ * ```
+ */
+export const hex = (hexStr: string, alpha: number = 255): MarkerColor => {
+  // Try 6-char hex first (#RRGGBB or RRGGBB)
+  const result6 = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hexStr);
+  if (result6) {
+    return {
+      r: parseInt(result6[1]!, 16),
+      g: parseInt(result6[2]!, 16),
+      b: parseInt(result6[3]!, 16),
+      a: alpha,
+    };
+  }
+
+  // Try 3-char hex (#RGB or RGB)
+  const result3 = /^#?([a-f\d])([a-f\d])([a-f\d])$/i.exec(hexStr);
+  if (result3) {
+    return {
+      r: parseInt(result3[1]! + result3[1]!, 16),
+      g: parseInt(result3[2]! + result3[2]!, 16),
+      b: parseInt(result3[3]! + result3[3]!, 16),
+      a: alpha,
+    };
+  }
+
+  // Fallback to black
+  return { r: 0, g: 0, b: 0, a: alpha };
+};
+
+/**
+ * Preset colors for convenience
+ * @example
+ * ```ts
+ * <NitroMarker backgroundColor={Colors.red} />
+ * ```
+ */
+export const Colors = {
+  /** White (255, 255, 255) */
+  white: rgb(255, 255, 255),
+  /** Black (0, 0, 0) */
+  black: rgb(0, 0, 0),
+  /** iOS system red (255, 59, 48) */
+  red: rgb(255, 59, 48),
+  /** iOS system blue (0, 122, 255) */
+  blue: rgb(0, 122, 255),
+  /** Material green (76, 175, 80) */
+  green: rgb(76, 175, 80),
+  /** iOS system orange (255, 149, 0) */
+  orange: rgb(255, 149, 0),
+  /** Dark gray (51, 51, 51) */
+  gray: rgb(51, 51, 51),
+  /** Light gray (240, 240, 240) */
+  lightGray: rgb(240, 240, 240),
+};