@mmapp/react 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/hooks/useGeolocation.ts

@@ -1,207 +0,0 @@
-/**
- * useGeolocation — GPS tracking hook for location-aware workflows.
- *
- * Provides real-time geolocation data using the browser's Geolocation API.
- * Supports both one-shot position queries and continuous watch mode
- * (critical for ride tracking, delivery, fleet management).
- *
- * Usage in .workflow.tsx:
- *   const { latitude, longitude, heading, speed, loading } = useGeolocation({
- *     enableHighAccuracy: true,
- *     watch: true,
- *   });
- *
- *   // Publish location to ride channel
- *   useOnChange('latitude', (lat) => {
- *     channel.publish('location', { lat, lng: longitude });
- *   });
- */
-
-import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Geolocation position data. */
-export interface GeoPosition {
-  /** Latitude in decimal degrees. */
-  latitude: number | null;
-  /** Longitude in decimal degrees. */
-  longitude: number | null;
-  /** Accuracy in meters. */
-  accuracy: number | null;
-  /** Altitude in meters (if available). */
-  altitude: number | null;
-  /** Altitude accuracy in meters (if available). */
-  altitudeAccuracy: number | null;
-  /** Heading in degrees from true north (if moving). */
-  heading: number | null;
-  /** Speed in meters per second (if moving). */
-  speed: number | null;
-  /** Timestamp of the position reading. */
-  timestamp: number | null;
-}
-
-/** Options for configuring geolocation. */
-export interface GeolocationOptions {
-  /** Use GPS for high-accuracy positions (uses more battery). */
-  enableHighAccuracy?: boolean;
-  /** Maximum age of cached position in ms (default: 0). */
-  maximumAge?: number;
-  /** Timeout for position request in ms (default: 10000). */
-  timeout?: number;
-  /** Continuously watch position changes (default: false). */
-  watch?: boolean;
-  /** Enable/disable tracking (default: true). */
-  enabled?: boolean;
-}
-
-/** Geolocation result returned by useGeolocation. */
-export interface GeolocationResult extends GeoPosition {
-  /** Whether the initial position is still loading. */
-  loading: boolean;
-  /** Geolocation error (permission denied, unavailable, etc.). */
-  error: GeolocationError | null;
-  /** Whether the browser supports geolocation. */
-  supported: boolean;
-  /** Manually request current position. */
-  getCurrentPosition: () => void;
-  /** Start continuous watch (if not already watching). */
-  startWatching: () => void;
-  /** Stop continuous watch. */
-  stopWatching: () => void;
-  /** Whether currently watching position. */
-  watching: boolean;
-}
-
-/** Geolocation error with code. */
-export interface GeolocationError {
-  /** Error code: 1=PERMISSION_DENIED, 2=POSITION_UNAVAILABLE, 3=TIMEOUT. */
-  code: number;
-  /** Human-readable error message. */
-  message: string;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-const INITIAL_POSITION: GeoPosition = {
-  latitude: null,
-  longitude: null,
-  accuracy: null,
-  altitude: null,
-  altitudeAccuracy: null,
-  heading: null,
-  speed: null,
-  timestamp: null,
-};
-
-/**
- * Real-time geolocation tracking via the browser Geolocation API.
- *
- * @param options - Geolocation configuration.
- * @returns Position data with loading/error states and control methods.
- */
-export function useGeolocation(options: GeolocationOptions = {}): GeolocationResult {
-  const {
-    enableHighAccuracy = false,
-    maximumAge = 0,
-    timeout = 10000,
-    watch = false,
-    enabled = true,
-  } = options;
-
-  const [position, setPosition] = useState<GeoPosition>(INITIAL_POSITION);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<GeolocationError | null>(null);
-  const [watching, setWatching] = useState(false);
-  const watchIdRef = useRef<number | null>(null);
-
-  const supported = typeof navigator !== 'undefined' && 'geolocation' in navigator;
-
-  const positionOptions: PositionOptions = useMemo(
-    () => ({ enableHighAccuracy, maximumAge, timeout }),
-    [enableHighAccuracy, maximumAge, timeout],
-  );
-
-  const handleSuccess = useCallback((pos: GeolocationPosition) => {
-    setPosition({
-      latitude: pos.coords.latitude,
-      longitude: pos.coords.longitude,
-      accuracy: pos.coords.accuracy,
-      altitude: pos.coords.altitude,
-      altitudeAccuracy: pos.coords.altitudeAccuracy,
-      heading: pos.coords.heading,
-      speed: pos.coords.speed,
-      timestamp: pos.timestamp,
-    });
-    setError(null);
-    setLoading(false);
-  }, []);
-
-  const handleError = useCallback((err: GeolocationPositionError) => {
-    setError({ code: err.code, message: err.message });
-    setLoading(false);
-  }, []);
-
-  const getCurrentPosition = useCallback(() => {
-    if (!supported) {
-      setError({ code: 0, message: 'Geolocation is not supported' });
-      setLoading(false);
-      return;
-    }
-    setLoading(true);
-    navigator.geolocation.getCurrentPosition(handleSuccess, handleError, positionOptions);
-  }, [supported, handleSuccess, handleError, positionOptions]);
-
-  const startWatching = useCallback(() => {
-    if (!supported || watchIdRef.current !== null) return;
-    const id = navigator.geolocation.watchPosition(handleSuccess, handleError, positionOptions);
-    watchIdRef.current = id;
-    setWatching(true);
-  }, [supported, handleSuccess, handleError, positionOptions]);
-
-  const stopWatching = useCallback(() => {
-    if (watchIdRef.current !== null) {
-      navigator.geolocation.clearWatch(watchIdRef.current);
-      watchIdRef.current = null;
-      setWatching(false);
-    }
-  }, []);
-
-  // Auto-start on mount
-  useEffect(() => {
-    if (!enabled || !supported) {
-      if (!supported) {
-        setError({ code: 0, message: 'Geolocation is not supported' });
-      }
-      setLoading(false);
-      return;
-    }
-
-    if (watch) {
-      startWatching();
-    } else {
-      getCurrentPosition();
-    }
-
-    return () => {
-      stopWatching();
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [enabled, watch, supported]);
-
-  const handle: GeolocationResult = {
-    ...position,
-    loading,
-    error,
-    supported,
-    getCurrentPosition,
-    startWatching,
-    stopWatching,
-    watching,
-  };
-  return handle;
-}

package/src/hooks/useMapView.ts

@@ -1,259 +0,0 @@
-/**
- * useMapView — Map state management for location-based workflows.
- *
- * Manages map viewport state (center, zoom, bounds) independent of
- * any specific map library. Works with Mapbox, Google Maps, Leaflet, etc.
- *
- * Usage in .workflow.tsx:
- *   const map = useMapView({
- *     initialCenter: { lat: 40.7128, lng: -74.0060 },
- *     initialZoom: 13,
- *   });
- *
- *   // Track driver position
- *   useOnChange('driverLocation', (loc) => {
- *     map.panTo(loc.lat, loc.lng);
- *   });
- *
- *   // Fit all markers in view
- *   map.fitBounds(markers.map(m => ({ lat: m.lat, lng: m.lng })));
- */
-
-import { useState, useCallback, useMemo } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** Geographic coordinate. */
-export interface LatLng {
-  lat: number;
-  lng: number;
-}
-
-/** Geographic bounds (rectangle). */
-export interface LatLngBounds {
-  north: number;
-  south: number;
-  east: number;
-  west: number;
-}
-
-/** A marker on the map. */
-export interface MapMarker {
-  id: string;
-  position: LatLng;
-  label?: string;
-  icon?: string;
-  data?: Record<string, unknown>;
-}
-
-/** Options for configuring the map view. */
-export interface MapViewOptions {
-  /** Initial center coordinate. */
-  initialCenter?: LatLng;
-  /** Initial zoom level (0-22). */
-  initialZoom?: number;
-  /** Minimum zoom level. */
-  minZoom?: number;
-  /** Maximum zoom level. */
-  maxZoom?: number;
-  /** Restrict panning to these bounds. */
-  maxBounds?: LatLngBounds;
-}
-
-/** Map view handle returned by useMapView. */
-export interface MapViewHandle {
-  /** Current center coordinate. */
-  center: LatLng;
-  /** Current zoom level. */
-  zoom: number;
-  /** Current viewport bounds. */
-  bounds: LatLngBounds | null;
-  /** Map markers. */
-  markers: MapMarker[];
-  /** Set the map center. */
-  setCenter: (lat: number, lng: number) => void;
-  /** Set the zoom level. */
-  setZoom: (zoom: number) => void;
-  /** Smoothly pan to a coordinate. */
-  panTo: (lat: number, lng: number) => void;
-  /** Adjust viewport to fit given coordinates. */
-  fitBounds: (points: LatLng[], padding?: number) => void;
-  /** Set viewport bounds (from map library callbacks). */
-  setBounds: (bounds: LatLngBounds) => void;
-  /** Add a marker. */
-  addMarker: (marker: MapMarker) => void;
-  /** Remove a marker by ID. */
-  removeMarker: (id: string) => void;
-  /** Update a marker's position. */
-  updateMarker: (id: string, position: LatLng) => void;
-  /** Clear all markers. */
-  clearMarkers: () => void;
-  /** Calculate distance between two points in meters. */
-  distance: (from: LatLng, to: LatLng) => number;
-}
-
-// =============================================================================
-// Internal
-// =============================================================================
-
-/** Haversine distance in meters. */
-function haversineDistance(from: LatLng, to: LatLng): number {
-  const R = 6371000; // Earth radius in meters
-  const dLat = ((to.lat - from.lat) * Math.PI) / 180;
-  const dLng = ((to.lng - from.lng) * Math.PI) / 180;
-  const a =
-    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
-    Math.cos((from.lat * Math.PI) / 180) *
-      Math.cos((to.lat * Math.PI) / 180) *
-      Math.sin(dLng / 2) *
-      Math.sin(dLng / 2);
-  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
-  return R * c;
-}
-
-/** Calculate bounds that contain all points. */
-function boundsFromPoints(points: LatLng[], padding: number): LatLngBounds {
-  let north = -90, south = 90, east = -180, west = 180;
-
-  for (const p of points) {
-    if (p.lat > north) north = p.lat;
-    if (p.lat < south) south = p.lat;
-    if (p.lng > east) east = p.lng;
-    if (p.lng < west) west = p.lng;
-  }
-
-  // Add padding (rough degree-based padding)
-  const latPad = (north - south) * padding;
-  const lngPad = (east - west) * padding;
-
-  return {
-    north: north + latPad,
-    south: south - latPad,
-    east: east + lngPad,
-    west: west - lngPad,
-  };
-}
-
-/** Calculate center from bounds. */
-function centerFromBounds(bounds: LatLngBounds): LatLng {
-  return {
-    lat: (bounds.north + bounds.south) / 2,
-    lng: (bounds.east + bounds.west) / 2,
-  };
-}
-
-/** Estimate zoom level from bounds. */
-function zoomFromBounds(bounds: LatLngBounds): number {
-  const latDiff = bounds.north - bounds.south;
-  const lngDiff = bounds.east - bounds.west;
-  const maxDiff = Math.max(latDiff, lngDiff);
-
-  if (maxDiff >= 360) return 0;
-  // Rough estimate: each zoom level halves the view
-  return Math.max(0, Math.min(20, Math.round(Math.log2(360 / maxDiff))));
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Map viewport state manager for location-based applications.
- *
- * @param options - Map configuration (center, zoom, bounds).
- * @returns Map view handle with viewport state and control methods.
- */
-export function useMapView(options: MapViewOptions = {}): MapViewHandle {
-  const {
-    initialCenter = { lat: 0, lng: 0 },
-    initialZoom = 10,
-    minZoom = 0,
-    maxZoom = 22,
-  } = options;
-
-  const [center, setCenterState] = useState<LatLng>(initialCenter);
-  const [zoom, setZoomState] = useState(initialZoom);
-  const [bounds, setBoundsState] = useState<LatLngBounds | null>(null);
-  const [markers, setMarkers] = useState<MapMarker[]>([]);
-
-  const setCenter = useCallback((lat: number, lng: number) => {
-    setCenterState({ lat, lng });
-  }, []);
-
-  const setZoom = useCallback(
-    (z: number) => {
-      setZoomState(Math.max(minZoom, Math.min(maxZoom, z)));
-    },
-    [minZoom, maxZoom],
-  );
-
-  const panTo = useCallback((lat: number, lng: number) => {
-    setCenterState({ lat, lng });
-  }, []);
-
-  const fitBounds = useCallback(
-    (points: LatLng[], padding = 0.1) => {
-      if (points.length === 0) return;
-
-      if (points.length === 1) {
-        setCenterState(points[0]);
-        setZoomState(15);
-        return;
-      }
-
-      const calculatedBounds = boundsFromPoints(points, padding);
-      setCenterState(centerFromBounds(calculatedBounds));
-      setZoomState(Math.max(minZoom, Math.min(maxZoom, zoomFromBounds(calculatedBounds))));
-      setBoundsState(calculatedBounds);
-    },
-    [minZoom, maxZoom],
-  );
-
-  const setBounds = useCallback((b: LatLngBounds) => {
-    setBoundsState(b);
-  }, []);
-
-  const addMarker = useCallback((marker: MapMarker) => {
-    setMarkers((prev) => [...prev.filter((m) => m.id !== marker.id), marker]);
-  }, []);
-
-  const removeMarker = useCallback((id: string) => {
-    setMarkers((prev) => prev.filter((m) => m.id !== id));
-  }, []);
-
-  const updateMarker = useCallback((id: string, position: LatLng) => {
-    setMarkers((prev) =>
-      prev.map((m) => (m.id === id ? { ...m, position } : m)),
-    );
-  }, []);
-
-  const clearMarkers = useCallback(() => {
-    setMarkers([]);
-  }, []);
-
-  const distance = useCallback((from: LatLng, to: LatLng) => {
-    return haversineDistance(from, to);
-  }, []);
-
-  return useMemo(
-    (): MapViewHandle => ({
-      center,
-      zoom,
-      bounds,
-      markers,
-      setCenter,
-      setZoom,
-      panTo,
-      fitBounds,
-      setBounds,
-      addMarker,
-      removeMarker,
-      updateMarker,
-      clearMarkers,
-      distance,
-    }),
-    [center, zoom, bounds, markers, setCenter, setZoom, panTo, fitBounds, setBounds, addMarker, removeMarker, updateMarker, clearMarkers, distance],
-  );
-}