@mint-ui/map 1.2.0-test.33 → 1.2.0-test.35

package/dist/components/mint-map/core/advanced/shared/context.d.ts

@@ -4,10 +4,23 @@ import { KonvaCanvasData } from "./types";
 /**
  * 다중 WoongCanvasMarker/WoongCanvasPolygon 인스턴스를 관리하기 위한 Context
  *
- * 용도:
- * - zIndex 기반 이벤트 우선순위 처리
+ * 여러 WoongCanvas 컴포넌트가 함께 사용될 때 zIndex 기반으로 이벤트 우선순위를 관리합니다.
+ *
+ * @remarks
+ * **주요 용도:**
+ * - zIndex 기반 이벤트 우선순위 처리 (높은 zIndex가 먼저 처리)
  * - 전역 클릭/호버 이벤트 조정
  * - 여러 레이어 간 상호작용 관리
+ *
+ * @example
+ * ```tsx
+ * <WoongCanvasProvider>
+ *   <WoongCanvasMarker data={markers} zIndex={10} />
+ *   <WoongCanvasPolygon data={polygons} zIndex={5} />
+ * </WoongCanvasProvider>
+ * ```
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
  */
 export interface ComponentInstance<T> {
     zIndex: number;
@@ -21,12 +34,68 @@ export interface ComponentInstance<T> {
     getSelectedIds: () => Set<string>;
     isInteractionDisabled: () => boolean;
 }
+/**
+ * WoongCanvas Context Value 인터페이스
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ */
 interface WoongCanvasContextValue {
+    /**
+     * 컴포넌트 인스턴스 등록
+     *
+     * @param instance 등록할 컴포넌트 인스턴스
+     */
     registerComponent: <T>(instance: ComponentInstance<T>) => void;
+    /**
+     * 컴포넌트 인스턴스 등록 해제
+     *
+     * @param instance 등록 해제할 컴포넌트 인스턴스
+     */
     unregisterComponent: <T>(instance: ComponentInstance<T>) => void;
 }
+/**
+ * WoongCanvasProvider 컴포넌트
+ *
+ * 다중 WoongCanvas 컴포넌트 인스턴스를 관리하는 Context Provider입니다.
+ * 여러 WoongCanvasMarker/WoongCanvasPolygon이 함께 사용될 때 전역 이벤트 조정을 수행합니다.
+ *
+ * @param props 컴포넌트 props
+ * @param props.children 자식 컴포넌트
+ *
+ * @remarks
+ * - zIndex 기반으로 이벤트 우선순위 처리
+ * - 전역 클릭/호버 이벤트 조정
+ * - 여러 레이어 간 상호작용 관리
+ *
+ * @example
+ * ```tsx
+ * <WoongCanvasProvider>
+ *   <WoongCanvasMarker data={markers} zIndex={10} />
+ *   <WoongCanvasPolygon data={polygons} zIndex={5} />
+ * </WoongCanvasProvider>
+ * ```
+ */
 export declare const WoongCanvasProvider: React.FC<{
     children: React.ReactNode;
 }>;
+/**
+ * WoongCanvas Context Hook
+ *
+ * WoongCanvasProvider로 감싸진 컴포넌트에서 Context에 접근할 수 있는 hook입니다.
+ *
+ * @returns WoongCanvasContextValue 또는 null (Provider 없으면)
+ *
+ * @remarks
+ * - Provider로 감싸지지 않으면 null 반환 (각 컴포넌트가 로컬 이벤트 처리)
+ * - Provider로 감싸져 있으면 전역 이벤트 조정 활성화
+ *
+ * @example
+ * ```typescript
+ * const context = useWoongCanvasContext();
+ * if (context) {
+ *   // Context 사용 중 (전역 이벤트 조정)
+ * }
+ * ```
+ */
 export declare const useWoongCanvasContext: () => WoongCanvasContextValue | null;
 export {};

package/dist/components/mint-map/core/advanced/shared/context.js

@@ -10,6 +10,29 @@ function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'defau
 var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
 
 var WoongCanvasContext = React.createContext(null);
+/**
+ * WoongCanvasProvider 컴포넌트
+ *
+ * 다중 WoongCanvas 컴포넌트 인스턴스를 관리하는 Context Provider입니다.
+ * 여러 WoongCanvasMarker/WoongCanvasPolygon이 함께 사용될 때 전역 이벤트 조정을 수행합니다.
+ *
+ * @param props 컴포넌트 props
+ * @param props.children 자식 컴포넌트
+ *
+ * @remarks
+ * - zIndex 기반으로 이벤트 우선순위 처리
+ * - 전역 클릭/호버 이벤트 조정
+ * - 여러 레이어 간 상호작용 관리
+ *
+ * @example
+ * ```tsx
+ * <WoongCanvasProvider>
+ *   <WoongCanvasMarker data={markers} zIndex={10} />
+ *   <WoongCanvasPolygon data={polygons} zIndex={5} />
+ * </WoongCanvasProvider>
+ * ```
+ */
+
 var WoongCanvasProvider = function (_a) {
   var children = _a.children;
   var controller = MintMapProvider.useMintMapController(); // Refs
@@ -20,7 +43,12 @@ var WoongCanvasProvider = function (_a) {
   var draggingRef = React.useRef(false);
   /**
    * 컴포넌트 등록 (zIndex 내림차순 정렬)
-   * 높은 zIndex가 먼저 처리됨
+   *
+   * 컴포넌트 인스턴스를 등록하고 zIndex 기준으로 내림차순 정렬합니다.
+   * 높은 zIndex를 가진 컴포넌트가 이벤트 처리에서 우선순위를 가집니다.
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   * @param instance 등록할 컴포넌트 인스턴스
    */
 
   var registerComponent = React.useCallback(function (instance) {
@@ -31,6 +59,12 @@ var WoongCanvasProvider = function (_a) {
   }, []);
   /**
    * 컴포넌트 등록 해제
+   *
+   * 컴포넌트 인스턴스를 등록 해제합니다.
+   * hover 중이던 컴포넌트면 hover 상태도 초기화합니다.
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   * @param instance 등록 해제할 컴포넌트 인스턴스
    */
 
   var unregisterComponent = React.useCallback(function (instance) {
@@ -46,6 +80,15 @@ var WoongCanvasProvider = function (_a) {
   }, []);
   /**
    * 전역 클릭 핸들러 (zIndex 우선순위)
+   *
+   * 모든 등록된 WoongCanvas 컴포넌트 중 zIndex가 높은 컴포넌트부터 클릭 이벤트를 처리합니다.
+   *
+   * @param event 클릭 이벤트 파라미터
+   *
+   * @remarks
+   * - zIndex가 높은 컴포넌트부터 순회하여 첫 번째 히트만 처리
+   * - 상호작용이 비활성화된 컴포넌트는 스킵
+   * - Context가 없으면 각 컴포넌트의 로컬 핸들러가 처리
    */
 
   var handleGlobalClick = React.useCallback(function (event) {
@@ -73,6 +116,16 @@ var WoongCanvasProvider = function (_a) {
   }, [controller]);
   /**
    * 전역 마우스 이동 핸들러 (zIndex 우선순위)
+   *
+   * 모든 등록된 WoongCanvas 컴포넌트 중 zIndex가 높은 컴포넌트부터 hover 이벤트를 처리합니다.
+   *
+   * @param event 마우스 이동 이벤트 파라미터
+   *
+   * @remarks
+   * - zIndex가 높은 컴포넌트부터 순회하여 첫 번째 히트만 처리
+   * - 상호작용이 비활성화된 컴포넌트는 스킵
+   * - 드래그 중이면 이벤트 무시 (성능 최적화)
+   * - hover 상태 변경 감지 후 이전 hover 해제 및 새 hover 설정
    */
 
   var handleGlobalMouseMove = React.useCallback(function (event) {
@@ -159,6 +212,26 @@ var WoongCanvasProvider = function (_a) {
     value: contextValue
   }, children);
 };
+/**
+ * WoongCanvas Context Hook
+ *
+ * WoongCanvasProvider로 감싸진 컴포넌트에서 Context에 접근할 수 있는 hook입니다.
+ *
+ * @returns WoongCanvasContextValue 또는 null (Provider 없으면)
+ *
+ * @remarks
+ * - Provider로 감싸지지 않으면 null 반환 (각 컴포넌트가 로컬 이벤트 처리)
+ * - Provider로 감싸져 있으면 전역 이벤트 조정 활성화
+ *
+ * @example
+ * ```typescript
+ * const context = useWoongCanvasContext();
+ * if (context) {
+ *   // Context 사용 중 (전역 이벤트 조정)
+ * }
+ * ```
+ */
+
 var useWoongCanvasContext = function () {
   var context = React.useContext(WoongCanvasContext);
   return context;

package/dist/components/mint-map/core/advanced/shared/helpers.d.ts

@@ -0,0 +1,28 @@
+import { EventParam, MapUIEventParam } from "../../../types";
+import type { MintMapController } from "../../MintMapController";
+import type { Offset } from "../../../types";
+/**
+ * 이벤트 유효성 검증 헬퍼
+ *
+ * @param event 이벤트 파라미터
+ * @param context Context가 있는지 여부
+ * @param controller MintMapController 인스턴스
+ * @returns 유효한 offset 또는 null
+ *
+ * @remarks
+ * Context가 있으면 전역 이벤트 핸들러가 처리하므로 로컬 핸들러는 스킵
+ */
+export declare const validateEvent: (event: EventParam<MapUIEventParam> | null | undefined, context: any, controller: MintMapController) => Offset | null;
+/**
+ * Map의 values를 배열로 변환 (최적화 버전)
+ *
+ * @param map 변환할 Map
+ * @returns Map의 값 배열
+ *
+ * @remarks
+ * Map.values()는 IterableIterator를 반환하므로 배열 변환이 필요할 때 사용합니다.
+ * 성능: O(n) 시간복잡도
+ *
+ * 최적화: Array.from을 사용하되, 크기를 미리 할당하여 메모리 재할당 최소화
+ */
+export declare const mapValuesToArray: <T>(map: Map<string, T>) => T[];

package/dist/components/mint-map/core/advanced/shared/helpers.js

@@ -0,0 +1,52 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * 이벤트 유효성 검증 헬퍼
+ *
+ * @param event 이벤트 파라미터
+ * @param context Context가 있는지 여부
+ * @param controller MintMapController 인스턴스
+ * @returns 유효한 offset 또는 null
+ *
+ * @remarks
+ * Context가 있으면 전역 이벤트 핸들러가 처리하므로 로컬 핸들러는 스킵
+ */
+var validateEvent = function (event, context, controller) {
+  var _a; // Context가 있으면 전역 핸들러가 처리
+
+
+  if (context) return null; // 이벤트 파라미터 검증
+
+  if (!((_a = event === null || event === void 0 ? void 0 : event.param) === null || _a === void 0 ? void 0 : _a.position)) return null;
+
+  try {
+    return controller.positionToOffset(event.param.position);
+  } catch (error) {
+    console.error('[WoongCanvas] validateEvent error:', error);
+    return null;
+  }
+};
+/**
+ * Map의 values를 배열로 변환 (최적화 버전)
+ *
+ * @param map 변환할 Map
+ * @returns Map의 값 배열
+ *
+ * @remarks
+ * Map.values()는 IterableIterator를 반환하므로 배열 변환이 필요할 때 사용합니다.
+ * 성능: O(n) 시간복잡도
+ *
+ * 최적화: Array.from을 사용하되, 크기를 미리 할당하여 메모리 재할당 최소화
+ */
+
+var mapValuesToArray = function (map) {
+  // Map이 비어있으면 빈 배열 반환 (메모리 할당 최소화)
+  if (map.size === 0) return []; // Array.from 사용 (TypeScript 컴파일러 호환성)
+
+  return Array.from(map.values());
+};
+
+exports.mapValuesToArray = mapValuesToArray;
+exports.validateEvent = validateEvent;

package/dist/components/mint-map/core/advanced/shared/hooks.d.ts

@@ -0,0 +1,144 @@
+import { MutableRefObject } from "react";
+import type { MintMapController } from "../../MintMapController";
+import type { Marker, MarkerOptions } from "../../../types";
+import type { KonvaCanvasData } from "./types";
+import type { BoundingBox } from "./viewport";
+import type { SpatialHashGrid } from "./performance";
+/**
+ * 공통 이벤트 핸들러 의존성 인터페이스
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ *
+ * @remarks
+ * 지도 이벤트 핸들러 생성 시 필요한 모든 의존성을 포함합니다.
+ */
+export interface EventHandlerDeps<T> {
+    controller: MintMapController;
+    containerRef: MutableRefObject<HTMLDivElement | null>;
+    markerRef: MutableRefObject<Marker | undefined>;
+    options: Pick<MarkerOptions, 'zIndex' | 'anchor' | 'visible'>;
+    prevCenterOffsetRef: MutableRefObject<{
+        x: number;
+        y: number;
+    } | null>;
+    accumTranslateRef: MutableRefObject<{
+        x: number;
+        y: number;
+    }>;
+    offsetCacheRef: MutableRefObject<any>;
+    boundingBoxCacheRef: MutableRefObject<Map<string, BoundingBox>>;
+    renderAllImmediate: () => void;
+}
+/**
+ * 지도 이벤트 핸들러 생성 함수
+ *
+ * 지도 이동, 줌, 드래그 등의 이벤트를 처리하는 핸들러들을 생성합니다.
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param deps 이벤트 핸들러 생성에 필요한 의존성
+ * @returns 지도 이벤트 핸들러 객체
+ *
+ * @example
+ * ```typescript
+ * const {
+ *   handleIdle,
+ *   handleZoomStart,
+ *   handleZoomEnd,
+ *   handleCenterChanged,
+ *   handleDragStart,
+ *   handleDragEnd,
+ * } = createMapEventHandlers({
+ *   controller,
+ *   containerRef,
+ *   markerRef,
+ *   options,
+ *   prevCenterOffsetRef,
+ *   accumTranslateRef,
+ *   offsetCacheRef,
+ *   boundingBoxCacheRef,
+ *   renderAllImmediate,
+ * });
+ * ```
+ */
+export declare const createMapEventHandlers: <T>(deps: EventHandlerDeps<T>) => {
+    handleIdle: () => void;
+    handleZoomStart: () => void;
+    handleZoomEnd: () => void;
+    handleCenterChanged: () => void;
+    handleDragStart: () => void;
+    handleDragEnd: () => void;
+};
+/**
+ * 공간 인덱스 빌드 (빠른 Hit Test를 위한 자료구조)
+ *
+ * Spatial Hash Grid에 모든 데이터의 바운딩 박스를 삽입합니다.
+ * 이를 통해 클릭/호버 시 O(1) 수준의 빠른 Hit Test가 가능합니다.
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param data 공간 인덱스에 삽입할 데이터 배열
+ * @param spatialIndex Spatial Hash Grid 인스턴스
+ * @param computeBoundingBox 바운딩 박스 계산 함수
+ *
+ * @remarks
+ * - 성능: O(n) 시간복잡도, n은 데이터 개수
+ * - 호출 시점: 데이터 변경 시 또는 지도 이동/줌 완료 시
+ *
+ * @example
+ * ```typescript
+ * buildSpatialIndex(
+ *   dataRef.current,
+ *   spatialIndexRef.current,
+ *   computeBoundingBox
+ * );
+ * ```
+ */
+export declare const buildSpatialIndex: <T>(data: KonvaCanvasData<T>[], spatialIndex: SpatialHashGrid<KonvaCanvasData<T>>, computeBoundingBox: (item: KonvaCanvasData<T>) => BoundingBox | null) => void;
+/**
+ * 선택 상태 동기화 유틸리티
+ *
+ * 데이터 변경 시 선택된 항목의 참조를 최신 데이터로 업데이트합니다.
+ * 화면 밖에 있는 선택된 항목도 선택 상태를 유지합니다.
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param data 최신 데이터 배열
+ * @param selectedIds 선택된 항목 ID Set
+ * @param selectedItemsMap 현재 선택된 항목 Map
+ * @returns 업데이트된 선택된 항목 Map
+ *
+ * @remarks
+ * - 성능: O(n + m), n은 전체 데이터 수, m은 선택된 항목 수
+ * - 화면 밖 데이터도 선택 상태 유지 (최신 데이터가 없으면 기존 데이터 유지)
+ *
+ * @example
+ * ```typescript
+ * selectedItemsMapRef.current = syncSelectedItems(
+ *   data,
+ *   selectedIdsRef.current,
+ *   selectedItemsMapRef.current
+ * );
+ * ```
+ */
+export declare const syncSelectedItems: <T>(data: KonvaCanvasData<T>[], selectedIds: Set<string>, selectedItemsMap: Map<string, KonvaCanvasData<T>>) => Map<string, KonvaCanvasData<T>>;
+/**
+ * 외부 selectedItems를 내부 상태로 동기화
+ *
+ * 외부에서 전달된 selectedItems prop을 내부 ref 상태로 동기화합니다.
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param externalSelectedItems 외부에서 전달된 선택된 항목 배열 (undefined면 동기화 안 함)
+ * @param selectedIdsRef 선택된 ID Set ref
+ * @param selectedItemsMapRef 선택된 항목 Map ref
+ *
+ * @remarks
+ * - externalSelectedItems가 undefined면 외부 제어가 아니므로 아무 작업도 하지 않음
+ * - 성능: O(m), m은 externalSelectedItems의 길이
+ *
+ * @example
+ * ```typescript
+ * useEffect(() => {
+ *   syncExternalSelectedItems(externalSelectedItems, selectedIdsRef, selectedItemsMapRef);
+ *   // 렌더링...
+ * }, [externalSelectedItems]);
+ * ```
+ */
+export declare const syncExternalSelectedItems: <T>(externalSelectedItems: KonvaCanvasData<T>[] | undefined, selectedIdsRef: MutableRefObject<Set<string>>, selectedItemsMapRef: MutableRefObject<Map<string, KonvaCanvasData<T>>>) => void;