gistda-sphere-react 1.0.0

package/src/hooks/useOverlays.ts

@@ -0,0 +1,278 @@
+import { useCallback, useMemo, useState } from "react";
+import type { Icon, Location, PopupOptions, Range } from "../types";
+
+interface BaseOverlay {
+  id: string;
+}
+
+export interface MarkerData extends BaseOverlay {
+  position: Location;
+  icon?: Icon;
+  title?: string;
+  detail?: string;
+  popup?: PopupOptions;
+  visibleRange?: Range;
+  clickable?: boolean;
+  draggable?: boolean;
+  zIndex?: number;
+  rotate?: number;
+}
+
+export interface PolygonData extends BaseOverlay {
+  positions: Location[];
+  title?: string;
+  detail?: string;
+  lineWidth?: number;
+  lineColor?: string;
+  fillColor?: string;
+  lineStyle?: "Solid" | "Dashed" | "Dot";
+  popup?: PopupOptions;
+  visibleRange?: Range;
+  clickable?: boolean;
+  draggable?: boolean;
+  editable?: boolean;
+  zIndex?: number;
+}
+
+export interface PolylineData extends BaseOverlay {
+  positions: Location[];
+  title?: string;
+  detail?: string;
+  lineWidth?: number;
+  lineColor?: string;
+  lineStyle?: "Solid" | "Dashed" | "Dot";
+  popup?: PopupOptions;
+  visibleRange?: Range;
+  clickable?: boolean;
+  draggable?: boolean;
+  editable?: boolean;
+  zIndex?: number;
+}
+
+export interface CircleData extends BaseOverlay {
+  center: Location;
+  radius: number;
+  title?: string;
+  detail?: string;
+  lineWidth?: number;
+  lineColor?: string;
+  fillColor?: string;
+  lineStyle?: "Solid" | "Dashed" | "Dot";
+  popup?: PopupOptions;
+  visibleRange?: Range;
+  clickable?: boolean;
+  draggable?: boolean;
+  zIndex?: number;
+}
+
+type OverlayInput<T extends BaseOverlay> = Omit<T, "id"> & { id?: string };
+
+interface UseOverlaysResult<T extends BaseOverlay> {
+  items: T[];
+  add: (data: OverlayInput<T>) => string;
+  update: (id: string, data: Partial<Omit<T, "id">>) => void;
+  remove: (id: string) => void;
+  clear: () => void;
+  get: (id: string) => T | undefined;
+}
+
+function generateId(): string {
+  return `overlay-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
+function useOverlayState<T extends BaseOverlay>(): UseOverlaysResult<T> {
+  const [items, setItems] = useState<T[]>([]);
+
+  const add = useCallback((data: OverlayInput<T>): string => {
+    const id = data.id ?? generateId();
+    const newItem = { ...data, id } as T;
+    setItems((prev) => [...prev, newItem]);
+    return id;
+  }, []);
+
+  const update = useCallback(
+    (id: string, data: Partial<Omit<T, "id">>): void => {
+      setItems((prev) =>
+        prev.map((item) => (item.id === id ? { ...item, ...data } : item))
+      );
+    },
+    []
+  );
+
+  const remove = useCallback((id: string): void => {
+    setItems((prev) => prev.filter((item) => item.id !== id));
+  }, []);
+
+  const clear = useCallback((): void => {
+    setItems([]);
+  }, []);
+
+  const get = useCallback(
+    (id: string): T | undefined => {
+      return items.find((item) => item.id === id);
+    },
+    [items]
+  );
+
+  return useMemo(
+    () => ({ items, add, update, remove, clear, get }),
+    [items, add, update, remove, clear, get]
+  );
+}
+
+/**
+ * Hook to manage markers with add/update/remove functionality.
+ *
+ * @example
+ * ```tsx
+ * function DrawingPanel() {
+ *   const { items: markers, add, remove, clear } = useMarkers();
+ *
+ *   const handleMapClick = (location: Location) => {
+ *     add({ position: location, title: `Marker ${markers.length + 1}` });
+ *   };
+ *
+ *   return (
+ *     <>
+ *       {markers.map((m) => (
+ *         <Marker
+ *           key={m.id}
+ *           position={m.position}
+ *           title={m.title}
+ *           onClick={() => remove(m.id)}
+ *         />
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useMarkers(): UseOverlaysResult<MarkerData> {
+  return useOverlayState<MarkerData>();
+}
+
+/**
+ * Hook to manage polygons with add/update/remove functionality.
+ *
+ * @example
+ * ```tsx
+ * function DrawingPanel() {
+ *   const { items: polygons, add, clear } = usePolygons();
+ *
+ *   const handleFinishDrawing = (positions: Location[]) => {
+ *     add({ positions, fillColor: 'rgba(255, 0, 0, 0.3)' });
+ *   };
+ *
+ *   return (
+ *     <>
+ *       {polygons.map((p) => (
+ *         <Polygon key={p.id} positions={p.positions} fillColor={p.fillColor} />
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function usePolygons(): UseOverlaysResult<PolygonData> {
+  return useOverlayState<PolygonData>();
+}
+
+/**
+ * Hook to manage polylines with add/update/remove functionality.
+ *
+ * @example
+ * ```tsx
+ * function DrawingPanel() {
+ *   const { items: polylines, add } = usePolylines();
+ *
+ *   return (
+ *     <>
+ *       {polylines.map((p) => (
+ *         <Polyline key={p.id} positions={p.positions} lineColor={p.lineColor} />
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function usePolylines(): UseOverlaysResult<PolylineData> {
+  return useOverlayState<PolylineData>();
+}
+
+/**
+ * Hook to manage circles with add/update/remove functionality.
+ *
+ * @example
+ * ```tsx
+ * function DrawingPanel() {
+ *   const { items: circles, add } = useCircles();
+ *
+ *   const handleAddCircle = (center: Location, radius: number) => {
+ *     add({ center, radius, fillColor: 'rgba(0, 0, 255, 0.3)' });
+ *   };
+ *
+ *   return (
+ *     <>
+ *       {circles.map((c) => (
+ *         <Circle key={c.id} center={c.center} radius={c.radius} fillColor={c.fillColor} />
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useCircles(): UseOverlaysResult<CircleData> {
+  return useOverlayState<CircleData>();
+}
+
+/**
+ * Hook that combines all overlay types into a single manager.
+ *
+ * @example
+ * ```tsx
+ * function DrawingPanel() {
+ *   const overlays = useOverlays();
+ *
+ *   const handleClearAll = () => {
+ *     overlays.markers.clear();
+ *     overlays.polygons.clear();
+ *     overlays.polylines.clear();
+ *     overlays.circles.clear();
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={handleClearAll}>Clear All</button>
+ *       {overlays.markers.items.map((m) => <Marker key={m.id} {...m} />)}
+ *       {overlays.polygons.items.map((p) => <Polygon key={p.id} {...p} />)}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useOverlays(): {
+  markers: UseOverlaysResult<MarkerData>;
+  polygons: UseOverlaysResult<PolygonData>;
+  polylines: UseOverlaysResult<PolylineData>;
+  circles: UseOverlaysResult<CircleData>;
+  clearAll: () => void;
+} {
+  const markers = useMarkers();
+  const polygons = usePolygons();
+  const polylines = usePolylines();
+  const circles = useCircles();
+
+  const clearAll = useCallback(() => {
+    markers.clear();
+    polygons.clear();
+    polylines.clear();
+    circles.clear();
+  }, [markers, polygons, polylines, circles]);
+
+  return useMemo(
+    () => ({ markers, polygons, polylines, circles, clearAll }),
+    [markers, polygons, polylines, circles, clearAll]
+  );
+}
+
+export type { BaseOverlay, OverlayInput, UseOverlaysResult };

package/src/hooks/useRoute.ts

@@ -0,0 +1,232 @@
+import { useCallback, useMemo } from "react";
+import { useMap } from "../context/SphereContext";
+import type {
+  GeometryOptions,
+  Location,
+  RouteLabelType,
+  RouteMode,
+  RouteType,
+  SphereMarker,
+  SpherePolyline,
+} from "../types";
+
+export interface RouteGuideStep {
+  instruction: string;
+  distance: number | string;
+  duration: number | string;
+  location: Location;
+}
+
+export interface UseRouteReturn {
+  isReady: boolean;
+  addDestination: (
+    destination: SphereMarker | Location,
+    mode?: RouteMode
+  ) => void;
+  insertDestination: (
+    index: number,
+    destination: SphereMarker | Location,
+    mode?: RouteMode
+  ) => void;
+  removeDestination: (destination: SphereMarker) => void;
+  removeDestinationAt: (index: number) => void;
+  clearDestinations: () => void;
+  clearPath: () => void;
+  clear: () => void;
+  reverse: () => void;
+  search: () => void;
+  getDistance: (format?: boolean) => number | string;
+  getInterval: (format?: boolean) => number | string;
+  getGuide: (format?: boolean) => RouteGuideStep[] | HTMLElement;
+  exportRouteLine: (options?: GeometryOptions) => SpherePolyline | null;
+  listDestinations: () => SphereMarker[];
+  size: () => number;
+  setMode: (mode: RouteMode) => void;
+  setModeAt: (index: number, mode: RouteMode) => void;
+  enableRouteType: (routeType: RouteType, state: boolean) => void;
+  setLabel: (label: RouteLabelType) => void;
+  setAuto: (state: boolean) => void;
+  setLanguage: (lang: string) => void;
+}
+
+export function useRoute(): UseRouteReturn {
+  const { map, isReady } = useMap();
+
+  const addDestination = useCallback(
+    (destination: SphereMarker | Location, mode?: RouteMode) => {
+      map?.Route?.add(destination, mode);
+    },
+    [map]
+  );
+
+  const insertDestination = useCallback(
+    (index: number, destination: SphereMarker | Location, mode?: RouteMode) => {
+      map?.Route?.insert(index, destination, mode);
+    },
+    [map]
+  );
+
+  const removeDestination = useCallback(
+    (destination: SphereMarker) => {
+      map?.Route?.remove(destination);
+    },
+    [map]
+  );
+
+  const removeDestinationAt = useCallback(
+    (index: number) => {
+      map?.Route?.removeAt(index);
+    },
+    [map]
+  );
+
+  const clearDestinations = useCallback(() => {
+    map?.Route?.clearDestination();
+  }, [map]);
+
+  const clearPath = useCallback(() => {
+    map?.Route?.clearPath();
+  }, [map]);
+
+  const clear = useCallback(() => {
+    map?.Route?.clear();
+  }, [map]);
+
+  const reverse = useCallback(() => {
+    map?.Route?.reverse();
+  }, [map]);
+
+  const search = useCallback(() => {
+    map?.Route?.search();
+  }, [map]);
+
+  const getDistance = useCallback(
+    (format = false): number | string => {
+      return map?.Route?.distance(format) ?? 0;
+    },
+    [map]
+  );
+
+  const getInterval = useCallback(
+    (format = false): number | string => {
+      return map?.Route?.interval(format) ?? 0;
+    },
+    [map]
+  );
+
+  const getGuide = useCallback(
+    (format = false): RouteGuideStep[] | HTMLElement => {
+      const result = map?.Route?.guide(format);
+      return (result as RouteGuideStep[] | HTMLElement) ?? [];
+    },
+    [map]
+  );
+
+  const exportRouteLine = useCallback(
+    (options?: GeometryOptions): SpherePolyline | null => {
+      return map?.Route?.exportRouteLine(options) ?? null;
+    },
+    [map]
+  );
+
+  const listDestinations = useCallback((): SphereMarker[] => {
+    return map?.Route?.list() ?? [];
+  }, [map]);
+
+  const size = useCallback((): number => {
+    return map?.Route?.size() ?? 0;
+  }, [map]);
+
+  const setMode = useCallback(
+    (mode: RouteMode) => {
+      map?.Route?.mode(mode);
+    },
+    [map]
+  );
+
+  const setModeAt = useCallback(
+    (index: number, mode: RouteMode) => {
+      map?.Route?.modeOf(index, mode);
+    },
+    [map]
+  );
+
+  const enableRouteType = useCallback(
+    (routeType: RouteType, state: boolean) => {
+      map?.Route?.enableRoute(routeType, state);
+    },
+    [map]
+  );
+
+  const setLabel = useCallback(
+    (label: RouteLabelType) => {
+      map?.Route?.label(label);
+    },
+    [map]
+  );
+
+  const setAuto = useCallback(
+    (state: boolean) => {
+      map?.Route?.auto(state);
+    },
+    [map]
+  );
+
+  const setLanguage = useCallback(
+    (lang: string) => {
+      map?.Route?.language(lang);
+    },
+    [map]
+  );
+
+  return useMemo(
+    () => ({
+      isReady,
+      addDestination,
+      insertDestination,
+      removeDestination,
+      removeDestinationAt,
+      clearDestinations,
+      clearPath,
+      clear,
+      reverse,
+      search,
+      getDistance,
+      getInterval,
+      getGuide,
+      exportRouteLine,
+      listDestinations,
+      size,
+      setMode,
+      setModeAt,
+      enableRouteType,
+      setLabel,
+      setAuto,
+      setLanguage,
+    }),
+    [
+      isReady,
+      addDestination,
+      insertDestination,
+      removeDestination,
+      removeDestinationAt,
+      clearDestinations,
+      clearPath,
+      clear,
+      reverse,
+      search,
+      getDistance,
+      getInterval,
+      getGuide,
+      exportRouteLine,
+      listDestinations,
+      size,
+      setMode,
+      setModeAt,
+      enableRouteType,
+      setLabel,
+      setAuto,
+      setLanguage,
+    ]
+  );
+}

package/src/hooks/useSearch.ts

@@ -0,0 +1,143 @@
+import { useCallback, useMemo } from "react";
+import { useMap } from "../context/SphereContext";
+import type {
+  AddressOptions,
+  Location,
+  NearPoiOptions,
+  SearchOptions,
+  SuggestOptions,
+} from "../types";
+
+export interface SearchResult {
+  data: object[];
+  total?: number;
+}
+
+export interface AddressResult {
+  address?: string;
+  subdistrict?: string;
+  district?: string;
+  province?: string;
+  postcode?: string;
+  geocode?: string;
+}
+
+export interface PoiResult {
+  id: string;
+  name: string;
+  location: Location;
+  category?: string;
+  distance?: number;
+}
+
+export interface UseSearchReturn {
+  isReady: boolean;
+  suggest: (keyword: string, options?: SuggestOptions) => Promise<SearchResult>;
+  search: (keyword: string, options?: SearchOptions) => Promise<SearchResult>;
+  address: (
+    location: Location,
+    options?: AddressOptions
+  ) => Promise<AddressResult>;
+  nearPoi: (
+    location: Location,
+    options?: NearPoiOptions
+  ) => Promise<PoiResult[]>;
+  clear: () => void;
+  enablePopup: (state: boolean) => void;
+  setLanguage: (lang: string) => void;
+}
+
+export function useSearch(): UseSearchReturn {
+  const { map, isReady } = useMap();
+
+  const suggest = useCallback(
+    async (
+      keyword: string,
+      options?: SuggestOptions
+    ): Promise<SearchResult> => {
+      if (!map?.Search) {
+        throw new Error("Search API not available");
+      }
+      return (await map.Search.suggest(keyword, options)) as SearchResult;
+    },
+    [map]
+  );
+
+  const search = useCallback(
+    async (keyword: string, options?: SearchOptions): Promise<SearchResult> => {
+      if (!map?.Search) {
+        throw new Error("Search API not available");
+      }
+      return (await map.Search.search(keyword, options)) as SearchResult;
+    },
+    [map]
+  );
+
+  const address = useCallback(
+    async (
+      location: Location,
+      options?: AddressOptions
+    ): Promise<AddressResult> => {
+      if (!map?.Search) {
+        throw new Error("Search API not available");
+      }
+      return (await map.Search.address(location, options)) as AddressResult;
+    },
+    [map]
+  );
+
+  const nearPoi = useCallback(
+    async (
+      location: Location,
+      options?: NearPoiOptions
+    ): Promise<PoiResult[]> => {
+      if (!map?.Search) {
+        throw new Error("Search API not available");
+      }
+      const result = await map.Search.nearPoi(location, options);
+      return (result as { data?: PoiResult[] }).data ?? (result as PoiResult[]);
+    },
+    [map]
+  );
+
+  const clear = useCallback(() => {
+    map?.Search?.clear();
+  }, [map]);
+
+  const enablePopup = useCallback(
+    (state: boolean) => {
+      map?.Search?.enablePopup(state);
+    },
+    [map]
+  );
+
+  const setLanguage = useCallback(
+    (lang: string) => {
+      map?.Search?.language(lang);
+    },
+    [map]
+  );
+
+  return useMemo(
+    () => ({
+      isReady,
+      suggest,
+      search,
+      address,
+      nearPoi,
+      clear,
+      enablePopup,
+      setLanguage,
+    }),
+    [
+      isReady,
+      suggest,
+      search,
+      address,
+      nearPoi,
+      clear,
+      enablePopup,
+      setLanguage,
+    ]
+  );
+}

package/src/hooks/useSphere.ts

@@ -0,0 +1,18 @@
+import { useSphereContext } from "../context/SphereContext";
+import type { SphereNamespace } from "../types";
+
+export function useSphere(): {
+  sphere: SphereNamespace | null;
+  isLoaded: boolean;
+  error: Error | null;
+  apiKey: string;
+} {
+  const { sphere, isLoaded, error, apiKey } = useSphereContext();
+
+  return {
+    sphere,
+    isLoaded,
+    error,
+    apiKey,
+  };
+}