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

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

@@ -7,33 +7,9 @@ var tslib = require('tslib');
 /**
  * 지도 이벤트 핸들러 생성 함수
  *
- * 지도 이동, 줌, 드래그 등의 이벤트를 처리하는 핸들러들을 생성합니다.
- *
  * @template T 마커/폴리곤 데이터의 추가 속성 타입
  * @param deps 이벤트 핸들러 생성에 필요한 의존성
  * @returns 지도 이벤트 핸들러 객체
- *
- * @example
- * ```typescript
- * const {
- *   handleIdle,
- *   handleZoomStart,
- *   handleZoomEnd,
- *   handleCenterChanged,
- *   handleDragStart,
- *   handleDragEnd,
- * } = createMapEventHandlers({
- *   controller,
- *   containerRef,
- *   markerRef,
- *   options,
- *   prevCenterOffsetRef,
- *   accumTranslateRef,
- *   offsetCacheRef,
- *   boundingBoxCacheRef,
- *   renderAllImmediate,
- * });
- * ```
  */
 
 var createMapEventHandlers = function (deps) {
@@ -45,14 +21,7 @@ var createMapEventHandlers = function (deps) {
       accumTranslateRef = deps.accumTranslateRef,
       offsetCacheRef = deps.offsetCacheRef,
       boundingBoxCacheRef = deps.boundingBoxCacheRef,
-      renderAllImmediate = deps.renderAllImmediate;
-  /**
-   * 지도 이동/줌 완료 시 처리
-   *
-   * - 캐시 초기화: 좌표 변환 결과가 변경되었으므로 캐시 무효화
-   * - 마커 위치 업데이트: 새로운 지도 위치에 맞게 마커 재배치
-   * - 렌더링: 새 위치에서 전체 렌더링 수행
-   */
+      renderAllImmediate = deps.renderAllImmediate; // 지도 이동/줌 완료 시 처리 (캐시 초기화 및 렌더링)
 
   var handleIdle = function () {
     prevCenterOffsetRef.current = null;
@@ -70,45 +39,34 @@ var createMapEventHandlers = function (deps) {
       position: bounds.nw
     }, options);
 
-    markerRef.current && controller.updateMarker(markerRef.current, markerOptions); // transform 제거 전에 새 데이터로 즉시 렌더링 (겹침 방지)
+    markerRef.current && controller.updateMarker(markerRef.current, markerOptions); // transform 제거 전에 새 데이터로 즉시 렌더링 (transform 제거 시 잠깐 빈 화면이 보이는 것 방지)
 
     if (containerRef.current) {
       containerRef.current.style.transform = '';
       containerRef.current.style.visibility = '';
-    } // 새 위치에서 렌더링
+    } // 새 위치에서 렌더링 (캐시는 이미 초기화됨)
 
 
     renderAllImmediate();
-  };
-  /**
-   * 줌 시작 시 처리 (일시적으로 숨김)
-   */
+  }; // 줌 시작 시 처리 (일시적으로 숨김)
 
 
   var handleZoomStart = function () {
-    if (containerRef.current) {
-      containerRef.current.style.visibility = 'hidden';
-    }
-  };
-  /**
-   * 줌 종료 시 처리 (다시 표시)
-   */
+    if (!containerRef.current) return;
+    containerRef.current.style.visibility = 'hidden';
+  }; // 줌 종료 시 처리 (다시 표시)
 
 
   var handleZoomEnd = function () {
-    if (containerRef.current) {
-      containerRef.current.style.visibility = '';
-    }
-  };
-  /**
-   * 지도 중심 변경 시 처리 (transform으로 이동 추적)
-   */
+    if (!containerRef.current) return;
+    containerRef.current.style.visibility = '';
+  }; // 지도 중심 변경 시 처리 (transform으로 이동 추적, 캐시 유지)
 
 
   var handleCenterChanged = function () {
     var center = controller.getCurrBounds().getCenter();
     var curr = controller.positionToOffset(center);
-    var prev = prevCenterOffsetRef.current;
+    var prev = prevCenterOffsetRef.current; // 첫 번째 호출 시 이전 위치 저장만 하고 종료
 
     if (!prev) {
       prevCenterOffsetRef.current = {
@@ -116,10 +74,12 @@ var createMapEventHandlers = function (deps) {
         y: curr.y
       };
       return;
-    }
+    } // 이전 위치와 현재 위치의 차이 계산 (이동 거리)
+
 
     var dx = prev.x - curr.x;
-    var dy = prev.y - curr.y;
+    var dy = prev.y - curr.y; // 누적 이동 거리 저장 (transform으로 화면만 이동, 캐시는 유지하여 성능 최적화)
+
     accumTranslateRef.current = {
       x: accumTranslateRef.current.x + dx,
       y: accumTranslateRef.current.y + dy
@@ -127,23 +87,15 @@ var createMapEventHandlers = function (deps) {
     prevCenterOffsetRef.current = {
       x: curr.x,
       y: curr.y
-    };
+    }; // CSS transform으로 컨테이너 이동 (캐시된 좌표는 그대로 유지)
 
     if (containerRef.current) {
       containerRef.current.style.transform = "translate(".concat(accumTranslateRef.current.x, "px, ").concat(accumTranslateRef.current.y, "px)");
     }
   };
-  /**
-   * 드래그 시작 처리
-   */
-
 
   var handleDragStart = function () {// 커서는 각 컴포넌트에서 처리
   };
-  /**
-   * 드래그 종료 처리
-   */
-
 
   var handleDragEnd = function () {// 커서는 각 컴포넌트에서 처리
   };
@@ -160,26 +112,10 @@ var createMapEventHandlers = function (deps) {
 /**
  * 공간 인덱스 빌드 (빠른 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
- * );
- * ```
  */
 
 var buildSpatialIndex = function (data, spatialIndex, computeBoundingBox) {
@@ -195,29 +131,13 @@ var buildSpatialIndex = function (data, spatialIndex, computeBoundingBox) {
   }
 };
 /**
- * 선택 상태 동기화 유틸리티
- *
- * 데이터 변경 시 선택된 항목의 참조를 최신 데이터로 업데이트합니다.
- * 화면 밖에 있는 선택된 항목도 선택 상태를 유지합니다.
+ * 선택 상태 동기화 (화면 밖 데이터도 선택 상태 유지)
  *
  * @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
- * );
- * ```
  */
 
 var syncSelectedItems = function (data, selectedIds, selectedItemsMap) {
@@ -245,24 +165,10 @@ var syncSelectedItems = function (data, selectedIds, selectedItemsMap) {
 /**
  * 외부 selectedItems를 내부 상태로 동기화
  *
- * 외부에서 전달된 selectedItems prop을 내부 ref 상태로 동기화합니다.
- *
  * @template T 마커/폴리곤 데이터의 추가 속성 타입
- * @param externalSelectedItems 외부에서 전달된 선택된 항목 배열 (undefined면 동기화 안 함)
+ * @param externalSelectedItems 외부에서 전달된 선택된 항목 배열
  * @param selectedIdsRef 선택된 ID Set ref
  * @param selectedItemsMapRef 선택된 항목 Map ref
- *
- * @remarks
- * - externalSelectedItems가 undefined면 외부 제어가 아니므로 아무 작업도 하지 않음
- * - 성능: O(m), m은 externalSelectedItems의 길이
- *
- * @example
- * ```typescript
- * useEffect(() => {
- *   syncExternalSelectedItems(externalSelectedItems, selectedIdsRef, selectedItemsMapRef);
- *   // 렌더링...
- * }, [externalSelectedItems]);
- * ```
  */
 
 var syncExternalSelectedItems = function (externalSelectedItems, selectedIdsRef, selectedItemsMapRef) {

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

@@ -1,98 +1,34 @@
 /**
- * 공간 인덱스 그리드 셀 크기 (px)
+ * 공간 인덱스 그리드 셀 크기 (픽셀 단위)
  *
- * 최적값 계산:
- * - 목표: 클릭 시 셀당 10~30개 항목만 체크 (빠른 Hit Test)
- * - 화면 크기: 1920×1080 기준
- * - 30,000개 항목 → 50px 셀 크기 = 약 800개 셀 = 셀당 ~37개
- *
- * 성능 비교 (30,000개 기준):
- * - 200px: 셀당 ~577개 → Hit Test O(577) ❌ 느림
- * - 50px:  셀당 ~37개  → Hit Test O(37)  ✅ 15배 빠름!
- *
- * 트레이드오프:
- * - 작을수록: Hit Test 빠름, 메모리 사용량 증가
- * - 클수록: 메모리 효율적, Hit Test 느림
+ * @default 50
  */
 export declare const SPATIAL_GRID_CELL_SIZE = 50;
 /**
- * 뷰포트 컬링 여유 공간 (px)
+ * 뷰포트 컬링 여유 공간 (픽셀 단위)
  *
- * 화면 밖 100px까지 렌더링하여 스크롤 시 부드러운 전환
- * 30,000개 중 실제 렌더링: 화면에 보이는 1,000~3,000개만
+ * @default 100
  */
 export declare const DEFAULT_CULLING_MARGIN = 100;
 /**
  * LRU 캐시 최대 항목 수
  *
- * 좌표 변환 결과 캐싱 (positionToOffset 연산 비용 절약)
- *
- * 최적값 계산:
- * - 전체 항목: 30,000개
- * - 캐시 크기: 30,000개 → 100% 히트율 (메모리: ~2.4MB)
- *
- * 메모리 사용량 (항목당 ~80 bytes):
- * - 10,000개: ~800KB  → 캐시 히트율 33% ❌
- * - 30,000개: ~2.4MB  → 캐시 히트율 100% ✅
- *
- * zoom/pan 시 어차피 clear() 호출되므로 메모리 누적 없음
+ * @default 30000
  */
 export declare const DEFAULT_MAX_CACHE_SIZE = 30000;
 /**
- * LRU (Least Recently Used) Cache
+ * LRU Cache (Least Recently Used)
  *
- * 메모리 제한을 위한 캐시 구현입니다. WoongCanvas 컴포넌트에서 좌표 변환 결과를 캐싱하는데 사용됩니다.
+ * 좌표 변환 결과를 캐싱하기 위한 캐시 구현
  *
  * @template K 캐시 키 타입
  * @template V 캐시 값 타입
- *
- * @remarks
- * **개선 사항**:
- * 1. get() 성능 향상: 접근 빈도 추적 없이 단순 조회만 수행 (delete+set 제거)
- * 2. set() 버그 수정: 기존 키 업데이트 시 maxSize 체크 로직 개선
- * 3. 메모리 효율: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
- *
- * **트레이드오프**:
- * - 장점: 읽기 성능 대폭 향상 (10,000번 get → 이전보다 2배 빠름)
- * - 단점: 접근 빈도가 아닌 삽입 순서 기반 eviction (FIFO)
- *
- * WoongCanvasMarker 사용 사례에 최적:
- * - 좌표 변환 결과는 zoom/pan 시 어차피 전체 초기화
- * - 접근 빈도 추적보다 빠른 조회가 더 중요
- *
- * @example
- * ```typescript
- * const cache = new LRUCache<string, Offset>(30000);
- * cache.set(item.id, offset);
- * const cached = cache.get(item.id);
- * ```
  */
 export declare class LRUCache<K, V> {
     private cache;
     private maxSize;
     constructor(maxSize?: number);
-    /**
-     * 캐시에서 값 조회
-     *
-     * @param key 조회할 키
-     * @returns 캐시된 값 또는 undefined (캐시 미스 시)
-     *
-     * @remarks
-     * - 성능: O(1) 해시 조회
-     * - 최적화: delete+set 제거로 읽기 성능 대폭 향상
-     */
     get(key: K): V | undefined;
-    /**
-     * 캐시에 값 저장
-     *
-     * @param key 저장할 키
-     * @param value 저장할 값
-     *
-     * @remarks
-     * - 기존 키 업데이트: 단순 덮어쓰기 (크기 변화 없음)
-     * - 신규 키 추가: 크기 체크 후 필요시 가장 오래된 항목 제거 (FIFO)
-     * - 성능: O(1) 평균 시간복잡도
-     */
     set(key: K, value: V): void;
     clear(): void;
     size(): number;
@@ -100,140 +36,25 @@ export declare class LRUCache<K, V> {
 }
 /**
  * Spatial Hash Grid (공간 해시 그리드)
- * 공간 인덱싱을 위한 그리드 기반 자료구조 (개선 버전)
  *
- * 개선 사항:
- * 1. 중복 삽입 방지: 같은 항목을 여러 번 insert 해도 안전
- * 2. 메모리 누수 방지: 기존 항목 자동 제거
- * 3. 성능 최적화: 불필요한 배열 생성 최소화
+ * 빠른 Hit Test를 위한 그리드 기반 공간 인덱싱 자료구조
  *
- * 사용 사례:
- * - 빠른 Hit Test (마우스 클릭 시 어떤 마커/폴리곤인지 찾기)
- * - 30,000개 항목 → 클릭 위치 주변 ~10개만 체크 (3,000배 빠름)
+ * @template T 인덱싱할 항목 타입
  */
 export declare class SpatialHashGrid<T> {
     private cellSize;
     private grid;
     private itemToCells;
     constructor(cellSize?: number);
-    /**
-     * 셀 키 생성 (x, y 좌표 → 그리드 셀 ID)
-     */
     private getCellKey;
-    /**
-     * 바운딩 박스가 걸치는 모든 셀 키 배열 반환
-     */
     private getCellsForBounds;
-    /**
-     * 항목 추가 (바운딩 박스 기반)
-     *
-     * 항목을 공간 인덱스에 추가합니다. 바운딩 박스가 걸치는 모든 셀에 삽입됩니다.
-     *
-     * @param item 추가할 항목
-     * @param minX 바운딩 박스 최소 X 좌표
-     * @param minY 바운딩 박스 최소 Y 좌표
-     * @param maxX 바운딩 박스 최대 X 좌표
-     * @param maxY 바운딩 박스 최대 Y 좌표
-     *
-     * @remarks
-     * - 중복 삽입 방지: 기존 항목이 있으면 먼저 제거 후 재삽입
-     * - 메모리 누수 방지: 이전 셀 참조 완전 제거
-     * - 성능: O(1) 평균 시간복잡도
-     */
     insert(item: T, minX: number, minY: number, maxX: number, maxY: number): void;
-    /**
-     * 항목 제거
-     *
-     * 공간 인덱스에서 항목을 제거합니다.
-     *
-     * @param item 제거할 항목
-     *
-     * @remarks
-     * - 메모리 누수 방지: 모든 셀에서 참조 완전 제거
-     * - 빈 셀 정리: 항목이 없어진 셀은 자동으로 정리됨
-     * - 성능: O(셀 개수), 보통 O(1)
-     */
     remove(item: T): void;
-    /**
-     * 항목 위치 업데이트
-     *
-     * 항목의 위치를 업데이트합니다. remove + insert의 편의 함수입니다.
-     *
-     * @param item 업데이트할 항목
-     * @param minX 새로운 바운딩 박스 최소 X 좌표
-     * @param minY 새로운 바운딩 박스 최소 Y 좌표
-     * @param maxX 새로운 바운딩 박스 최대 X 좌표
-     * @param maxY 새로운 바운딩 박스 최대 Y 좌표
-     */
     update(item: T, minX: number, minY: number, maxX: number, maxY: number): void;
-    /**
-     * 점 주변의 항목 조회 (1개 셀만)
-     *
-     * 특정 좌표가 속한 셀의 모든 항목을 반환합니다.
-     *
-     * @param x 조회할 X 좌표
-     * @param y 조회할 Y 좌표
-     * @returns 해당 셀의 항목 배열 (없으면 빈 배열)
-     *
-     * @remarks
-     * - 성능: O(해당 셀의 항목 수) - 보통 ~10개 (30,000개 전체를 체크하지 않음)
-     * - Hit Test에 최적화된 메서드
-     * - 빈 배열 재사용으로 메모리 할당 최소화
-     *
-     * @example
-     * ```typescript
-     * const candidates = grid.queryPoint(mouseX, mouseY);
-     * for (const item of candidates) {
-     *   if (isPointInItem(item, mouseX, mouseY)) {
-     *     return item;
-     *   }
-     * }
-     * ```
-     */
     queryPoint(x: number, y: number): T[];
-    /**
-     * 영역 내 항목 조회
-     *
-     * 특정 영역(바운딩 박스)과 교차하는 모든 항목을 반환합니다.
-     *
-     * @param minX 영역 최소 X 좌표
-     * @param minY 영역 최소 Y 좌표
-     * @param maxX 영역 최대 X 좌표
-     * @param maxY 영역 최대 Y 좌표
-     * @returns 영역과 교차하는 항목 배열 (중복 제거됨)
-     *
-     * @remarks
-     * - 성능: O(셀 개수 × 셀당 평균 항목 수)
-     * - Set으로 중복 제거 보장 (항목이 여러 셀에 걸쳐 있어도 한 번만 반환)
-     * - Viewport Culling에 유용
-     */
     queryBounds(minX: number, minY: number, maxX: number, maxY: number): T[];
-    /**
-     * 항목 존재 여부 확인
-     *
-     * @param item 확인할 항목
-     * @returns 항목이 인덱스에 있으면 true, 아니면 false
-     *
-     * @remarks
-     * - 성능: O(1) 해시 조회
-     */
     has(item: T): boolean;
-    /**
-     * 전체 초기화
-     */
     clear(): void;
-    /**
-     * 통계 정보
-     *
-     * 공간 인덱스의 현재 상태를 반환합니다. 디버깅 및 성능 분석에 유용합니다.
-     *
-     * @returns 통계 정보 객체
-     *
-     * @remarks
-     * - totalCells: 현재 사용 중인 셀 개수
-     * - totalItems: 인덱스에 등록된 고유 항목 수 (정확)
-     * - avgItemsPerCell: 셀당 평균 항목 수
-     */
     stats(): {
         totalCells: number;
         totalItems: number;