@mint-ui/map 1.2.0-test.24 → 1.2.0-test.25

package/dist/components/mint-map/core/advanced/woongCanvas/WoongCanvasLayer.d.ts

@@ -84,54 +84,13 @@ declare const WoongCanvasLayer: <T>(props: WoongCanvasLayerProps<T>) => React.Re
 /**
  * 🚀 WoongCanvasLayer - Konva 기반 초고성능 마커/폴리곤 렌더링 컴포넌트
  *
- * 30,000개 이상의 마커/폴리곤을 60fps로 렌더링하는 최적화된 Canvas 레이어 시스템입니다.
- *
- * ## 🎯 주요 특징
+ * ## 📌 주요 특징
  * - **30,000개 이상의 폴리곤/마커를 60fps로 렌더링**
  * - **Multi-Layer 아키텍처**: Base/Animation/Event 레이어 분리
  * - **Spatial Hash Grid**: O(1) 수준의 빠른 Hit Test
  * - **LRU 캐시**: 좌표 변환 결과 캐싱으로 성능 최적화
  * - **Viewport Culling**: 화면에 보이는 영역만 렌더링
  * - **Discriminated Union Props**: 타입 안전한 MARKER/POLYGON 모드
- * - **topOnHover + renderEvent 조합**: hover된 항목을 최상단에 표시
- *
- * ## 📋 Props API
- *
- * ### 공통 Props (MARKER & POLYGON 모두 사용)
- * @param data - 렌더링할 데이터 배열
- * @param dataType - 'MARKER' 또는 'POLYGON'
- * @param onClick - 클릭 시 호출되는 콜백 함수
- * @param onMouseOver - Hover 시작 시 호출되는 콜백 함수
- * @param onMouseOut - Hover 종료 시 호출되는 콜백 함수
- * @param enableMultiSelect - 다중 선택 활성화 여부 (기본: false)
- * @param topOnHover - Hover 시 최상단 표시 여부 (기본: false)
- * @param enableViewportCulling - 뷰포트 컬링 활성화 여부 (기본: true)
- * @param cullingMargin - 컬링 여유 공간 (기본: 100px)
- * @param maxCacheSize - LRU 캐시 최대 크기 (기본: 30000)
- * @param selectedItems - 외부 제어 선택 상태
- * @param selectedItem - 단일 선택 아이템
- * @param disableInteraction - 모든 상호작용 비활성화 (기본: false)
- * @param zIndex - 레이어 순서 (기본: 0)
- * @param visible - 표시 여부 (기본: true)
- *
- * ### MARKER 타입 전용 Props
- * @param renderBase - Base Layer 렌더링 함수 (필수)
- * @param renderAnimation - Animation Layer 렌더링 함수 (선택)
- * @param renderEvent - Event Layer 렌더링 함수 (선택)
- *
- * ### POLYGON 타입 전용 Props
- * @param baseFillColor - 기본 채우기 색상 (필수)
- * @param baseStrokeColor - 기본 테두리 색상 (필수)
- * @param baseLineWidth - 기본 테두리 두께 (필수)
- * @param selectedFillColor - 선택 채우기 색상 (선택)
- * @param selectedStrokeColor - 선택 테두리 색상 (선택)
- * @param selectedLineWidth - 선택 테두리 두께 (선택)
- * @param activeFillColor - 마지막 선택 채우기 색상 (선택)
- * @param activeStrokeColor - 마지막 선택 테두리 색상 (선택)
- * @param activeLineWidth - 마지막 선택 테두리 두께 (선택)
- * @param hoveredFillColor - Hover 채우기 색상 (선택)
- * @param hoveredStrokeColor - Hover 테두리 색상 (선택)
- * @param hoveredLineWidth - Hover 테두리 두께 (선택)
  *
  * ## 🎯 사용 방법
  *
@@ -146,9 +105,9 @@ declare const WoongCanvasLayer: <T>(props: WoongCanvasLayerProps<T>) => React.Re
  *   selectedFillColor="rgba(255, 193, 7, 0.7)"
  *   selectedStrokeColor="rgba(255, 152, 0, 1)"
  *   selectedLineWidth={4}
- *   hoveredFillColor="rgba(100, 150, 255, 0.8)"
- *   hoveredStrokeColor="rgba(0, 100, 200, 1)"
- *   hoveredLineWidth={3}
+ *   hoveredFillColor="rgba(100, 150, 255, 0.8)"  // optional
+ *   hoveredStrokeColor="rgba(0, 100, 200, 1)"    // optional
+ *   hoveredLineWidth={3}                         // optional
  *   enableMultiSelect={true}
  *   onClick={handleClick}
  * />
@@ -159,35 +118,14 @@ declare const WoongCanvasLayer: <T>(props: WoongCanvasLayerProps<T>) => React.Re
  * <WoongCanvasLayer
  *   dataType={CanvasDataType.MARKER}
  *   data={markers}
- *   renderBase={renderMarkerBase}
- *   renderAnimation={renderMarkerAnimation}
- *   renderEvent={renderMarkerEvent}
+ *   renderBase={renderMarkerBase}              // required
+ *   renderAnimation={renderMarkerAnimation}    // optional
+ *   renderEvent={renderMarkerEvent}            // optional
  *   topOnHover={true}
  *   onClick={handleClick}
  * />
  * ```
  *
- * ### 3️⃣ topOnHover + renderEvent 조합
- *
- * `topOnHover={true}`와 `renderEvent`를 함께 사용하면 hover된 항목이 최상단에 표시됩니다:
- *
- * ```tsx
- * <WoongCanvasLayer
- *   dataType={CanvasDataType.MARKER}
- *   data={markers}
- *   renderBase={renderMarkerBase}
- *   renderEvent={renderMarkerEvent}
- *   topOnHover={true}
- *   onClick={handleClick}
- * />
- * ```
- *
- * **동작 방식:**
- * 1. **Base Layer**: hover된 항목을 제외하고 일반 항목들 렌더링
- * 2. **Event Layer**:
- *    - 먼저 hover된 항목을 제외한 나머지 항목들 렌더링
- *    - 그 다음 hover된 항목을 최상단에 렌더링 (시각적 우선순위)
- *
  * ## 📊 데이터 형식
  * ```typescript
  * const data: KonvaCanvasData<T>[] = [
@@ -199,7 +137,6 @@ declare const WoongCanvasLayer: <T>(props: WoongCanvasLayerProps<T>) => React.Re
  *     // MARKER: boxWidth/boxHeight 권장 (Hit Test 정확도)
  *     boxWidth: 60,
  *     boxHeight: 75,
- *     tailHeight: 9,  // 꼬리 높이 (Viewport Culling용, Hit Test 제외)
  *     // 커스텀 데이터
  *     ...customData
  *   }
@@ -220,8 +157,6 @@ declare const WoongCanvasLayer: <T>(props: WoongCanvasLayerProps<T>) => React.Re
  * tempCtx.font = 'bold 15px Arial';
  * const boxWidth = Math.max(60, tempCtx.measureText(text).width + 20);
  *
- * @see {@link ./README.md} 전체 문서
- * @version 2.2.1
- * @since 2.0.0
+ * @see {@link https://github.com/your-repo/docs/WoongCanvasLayer.md} 전체 문서
  */
 export default WoongCanvasLayer;

package/dist/components/mint-map/core/advanced/woongCanvas/WoongCanvasLayer.js

@@ -59,20 +59,20 @@ var WoongCanvasLayer = function (props) {
   var divElement = divRef.current;
   var containerRef = React.useRef(null);
   var markerRef = React.useRef(); // --------------------------------------------------------------------------
-  // Konva Refs - Multi-Layer 아키텍처
+  // Konva Refs
   // --------------------------------------------------------------------------
 
   var stageRef = React.useRef(null);
   var baseLayerRef = React.useRef(null);
   var animationLayerRef = React.useRef(null);
   var eventLayerRef = React.useRef(null); // --------------------------------------------------------------------------
-  // Data Refs - 데이터 동기화 및 상태 관리
+  // Data Refs - 선택 및 Hover 상태 관리
   // --------------------------------------------------------------------------
 
   /** data prop을 ref로 추적 (stale closure 방지, useEffect에서 동기화) */
 
   var dataRef = React.useRef(data); // --------------------------------------------------------------------------
-  // State Refs - 선택 및 Hover 상태 관리 (성능 최적화)
+  // State Refs - 선택 및 Hover 상태 관리
   // --------------------------------------------------------------------------
 
   /** 상호작용 비활성화 상태 (Ref로 관리하여 클로저 문제 해결) */
@@ -113,7 +113,7 @@ var WoongCanvasLayer = function (props) {
    */
 
   var selectedItemsMapRef = React.useRef(new Map()); // --------------------------------------------------------------------------
-  // Drag Refs - 지도 드래그 상태 관리
+  // Drag Refs
   // --------------------------------------------------------------------------
 
   var draggingRef = React.useRef(false);
@@ -122,7 +122,7 @@ var WoongCanvasLayer = function (props) {
     x: 0,
     y: 0
   }); // --------------------------------------------------------------------------
-  // Performance Refs - 성능 최적화 (캐싱 & 인덱싱)
+  // Performance Refs (캐싱 & 최적화)
   // --------------------------------------------------------------------------
 
   /** 좌표 변환 결과 LRU 캐시 */
@@ -137,7 +137,7 @@ var WoongCanvasLayer = function (props) {
   /** 뷰포트 경계 캐시 (Viewport Culling) */
 
   var viewportRef = React.useRef(null); // --------------------------------------------------------------------------
-  // 유틸리티 함수: 뷰포트 관리 (Viewport Culling)
+  // 유틸리티 함수: 뷰포트 관리
   // --------------------------------------------------------------------------
 
   /**
@@ -216,7 +216,7 @@ var WoongCanvasLayer = function (props) {
 
     return result;
   }; // --------------------------------------------------------------------------
-  // 유틸리티 함수: 바운딩 박스 계산 (Viewport Culling 최적화)
+  // 유틸리티 함수: 바운딩 박스 계산
   // --------------------------------------------------------------------------
 
   /**
@@ -330,14 +330,11 @@ var WoongCanvasLayer = function (props) {
   var renderEvent = dataType === types.CanvasDataType.MARKER ? props.renderEvent : function () {
     var polygonProps = props;
     return renderer.renderPolygonEvent(polygonProps.baseFillColor, polygonProps.baseStrokeColor, polygonProps.baseLineWidth, polygonProps.selectedFillColor, polygonProps.selectedStrokeColor, polygonProps.selectedLineWidth, polygonProps.activeFillColor, polygonProps.activeStrokeColor, polygonProps.activeLineWidth, polygonProps.hoveredFillColor, polygonProps.hoveredStrokeColor, polygonProps.hoveredLineWidth);
-  }(); // --------------------------------------------------------------------------
-  // 렌더링 함수: Base Layer (기본 상태 렌더링)
-  // --------------------------------------------------------------------------
-
+  }();
   /**
    * Base 레이어 렌더링 (뷰포트 컬링 적용, 선택된 마커 제외)
    *
-   * 🔥 성능 최적화:
+   * 🔥 최적화:
    * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
    * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
    * 3. 클로저로 최신 데이터 참조
@@ -403,14 +400,11 @@ var WoongCanvasLayer = function (props) {
 
 
     layer.batchDraw();
-  }; // --------------------------------------------------------------------------
-  // 렌더링 함수: Animation Layer (선택된 항목 애니메이션)
-  // --------------------------------------------------------------------------
-
+  };
   /**
    * Animation 레이어 렌더링 (선택된 마커 애니메이션)
    *
-   * 🔥 성능 최적화: sceneFunc 내부에서 최신 items 참조
+   * 🔥 최적화: sceneFunc 내부에서 최신 items 참조
    * - 선택 변경 시에만 재생성
    * - 지도 이동 시에는 기존 Animation 계속 실행
    */
@@ -426,23 +420,14 @@ var WoongCanvasLayer = function (props) {
       items: dataRef.current,
       utils: renderUtils
     });
-  }; // --------------------------------------------------------------------------
-  // 렌더링 함수: Event Layer (상호작용 상태 렌더링)
-  // --------------------------------------------------------------------------
-
+  };
   /**
    * Event 레이어 렌더링 (hover + 선택 상태 표시)
    *
-   * 🔥 성능 최적화:
+   * 🔥 최적화:
    * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
    * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
    * 3. 클로저로 최신 데이터 참조
-   *
-   * 🎯 topOnHover + renderEvent 조합 지원:
-   * - topOnHover가 true이고 renderEvent가 있으면:
-   *   1. 먼저 hover된 항목을 제외한 나머지 항목들 렌더링
-   *   2. 그 다음 hover된 항목을 최상단에 렌더링 (시각적 우선순위)
-   * - topOnHover가 false이거나 renderEvent가 없으면 일반 렌더링
    */
 
 
@@ -459,35 +444,16 @@ var WoongCanvasLayer = function (props) {
       shape = new Konva__default["default"].Shape({
         name: 'event-render-shape',
         sceneFunc: function (context, shape) {
-          var ctx = context; // 클로저로 최신 ref 값 참조 (안전한 처리)
+          var ctx = context; // 클로저로 최신 ref 값 참조
 
           var selectedItems = Array.from(selectedItemsMapRef.current.values());
-          var hovered = hoveredItemRef.current;
-          var selectedItem = selectedItemRef.current; // topOnHover가 true이면 hover된 항목을 최상단에 렌더링
-
-          if (topOnHover && hovered) {
-            // hover된 항목만 최상단에 렌더링 (renderEvent는 한 번만 호출)
-            var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
-
-            if (isHoveredInViewport) {
-              renderEvent({
-                ctx: ctx,
-                hoveredItem: hovered,
-                utils: renderUtils,
-                selectedItems: selectedItems,
-                selectedItem: selectedItem
-              });
-            }
-          } else {
-            // topOnHover가 false이거나 hover된 항목이 없으면 일반 렌더링
-            renderEvent({
-              ctx: ctx,
-              hoveredItem: hovered,
-              utils: renderUtils,
-              selectedItems: selectedItems,
-              selectedItem: selectedItem
-            });
-          }
+          renderEvent({
+            ctx: ctx,
+            hoveredItem: hoveredItemRef.current,
+            utils: renderUtils,
+            selectedItems: selectedItems,
+            selectedItem: selectedItemRef.current
+          });
         },
         perfectDrawEnabled: false,
         listening: false,
@@ -598,7 +564,7 @@ var WoongCanvasLayer = function (props) {
       containerRef.current.style.transform = "translate(".concat(accumTranslateRef.current.x, "px, ").concat(accumTranslateRef.current.y, "px)");
     }
   }; // --------------------------------------------------------------------------
-  // Hit Test & 상태 관리 (이벤트 처리)
+  // Hit Test & 상태 관리
   // --------------------------------------------------------------------------
 
   /**
@@ -768,7 +734,7 @@ var WoongCanvasLayer = function (props) {
     }
   };
   /**
-   * 마우스 이동 이벤트 처리 (hover 감지 및 상태 업데이트)
+   * 마우스 이동 이벤트 처리 (hover 감지)
    */
 
 
@@ -812,7 +778,7 @@ var WoongCanvasLayer = function (props) {
     controller.setMapCursor('grab');
   };
   /**
-   * 마우스가 canvas를 벗어날 때 hover 상태 정리
+   * 마우스가 canvas를 벗어날 때 hover cleanup
    */
 
 
@@ -872,7 +838,7 @@ var WoongCanvasLayer = function (props) {
       }
     }
   }, [options]); // --------------------------------------------------------------------------
-  // Lifecycle: Konva 초기화 및 이벤트 리스너 등록 (컴포넌트 마운트)
+  // Lifecycle: Konva 초기화 및 이벤트 리스너 등록
   // --------------------------------------------------------------------------
 
   React.useEffect(function () {
@@ -998,32 +964,26 @@ var WoongCanvasLayer = function (props) {
     };
   }, []); // 초기화는 한 번만
   // --------------------------------------------------------------------------
-  // Lifecycle: disableInteraction 동기화 (상호작용 상태 관리)
+  // Lifecycle: disableInteraction 동기화
   // --------------------------------------------------------------------------
 
   React.useEffect(function () {
     disableInteractionRef.current = disableInteraction;
   }, [disableInteraction]); // --------------------------------------------------------------------------
-  // Lifecycle: 외부 selectedItems 동기화 (선택 상태 관리)
+  // Lifecycle: 외부 selectedItems 동기화
   // --------------------------------------------------------------------------
 
   React.useEffect(function () {
     if (!stageRef.current) return; // externalSelectedItems가 undefined면 외부 제어 안 함
 
-    if (externalSelectedItems === undefined) return; // 외부에서 전달된 selectedItems로 동기화 (안전한 처리)
+    if (externalSelectedItems === undefined) return; // 외부에서 전달된 selectedItems로 동기화
 
     var newSelectedIds = new Set();
-    var newSelectedItemsMap = new Map(); // selectedItems가 배열인지 확인하고 안전하게 처리
-
-    if (Array.isArray(externalSelectedItems)) {
-      externalSelectedItems.forEach(function (item) {
-        if (item && item.id) {
-          newSelectedIds.add(item.id);
-          newSelectedItemsMap.set(item.id, item);
-        }
-      });
-    }
-
+    var newSelectedItemsMap = new Map();
+    externalSelectedItems.forEach(function (item) {
+      newSelectedIds.add(item.id);
+      newSelectedItemsMap.set(item.id, item);
+    });
     selectedIdsRef.current = newSelectedIds;
     selectedItemsMapRef.current = newSelectedItemsMap; // 렌더링
 
@@ -1032,17 +992,17 @@ var WoongCanvasLayer = function (props) {
     doRenderEvent();
   }, [externalSelectedItems]); // 배열 자체를 dependency로 사용
   // --------------------------------------------------------------------------
-  // Lifecycle: 외부 selectedItem 변경 시 Event Layer 리렌더링 (단일 선택 관리)
+  // Lifecycle: 외부 selectedItem 변경 시 Event Layer 리렌더링
   // --------------------------------------------------------------------------
 
   React.useEffect(function () {
-    if (!stageRef.current) return; // Ref 동기화 (안전한 처리)
+    if (!stageRef.current) return; // Ref 동기화
 
-    selectedItemRef.current = externalSelectedItem || null; // selectedItem이 변경되면 Event Layer만 다시 그림
+    selectedItemRef.current = externalSelectedItem; // selectedItem이 변경되면 Event Layer만 다시 그림
 
     doRenderEvent();
   }, [externalSelectedItem]); // --------------------------------------------------------------------------
-  // Lifecycle: 데이터 변경 시 렌더링 (데이터 동기화 및 최적화)
+  // Lifecycle: 데이터 변경 시 렌더링
   // --------------------------------------------------------------------------
 
   React.useEffect(function () {
@@ -1099,10 +1059,7 @@ var WoongCanvasLayer = function (props) {
     selectedItemsMapRef.current = newSelectedItemsMap; // 즉시 렌더링
 
     renderAllImmediate();
-  }, [data]); // --------------------------------------------------------------------------
-  // Render - React Portal을 통한 DOM 렌더링
-  // --------------------------------------------------------------------------
-
+  }, [data]);
   return reactDom.createPortal(React__default["default"].createElement("div", {
     ref: containerRef,
     style: {

package/dist/components/mint-map/core/advanced/woongCanvas/index.d.ts

@@ -1,13 +1,3 @@
-/**
- * @fileoverview WoongCanvasLayer 모듈의 메인 엔트리 포인트
- *
- * 이 파일은 WoongCanvasLayer 컴포넌트와 관련된 모든 타입, 유틸리티,
- * 성능 최적화 클래스들을 외부로 노출합니다.
- *
- * @version 2.2.1
- * @since 2.0.0
- * @author 박건웅
- */
 export { default as WoongCanvasLayer } from "./WoongCanvasLayer";
 export * from "./WoongCanvasLayer";
 export * from "./shared";

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

@@ -2,99 +2,31 @@ import React from "react";
 import { Offset } from "../../../../types";
 import { KonvaCanvasData } from "./types";
 /**
- * @fileoverview 다중 WoongCanvasLayer 인스턴스를 관리하기 위한 React Context
+ * 다중 WoongKonvaMarker 인스턴스를 관리하기 위한 Context
  *
- * 이 Context는 여러 개의 WoongCanvasLayer가 동시에 사용될 때 이벤트 우선순위를
- * 관리하고 전역 클릭/호버 이벤트를 조정합니다.
- *
- * ## 주요 기능
- * - **zIndex 기반 이벤트 우선순위**: 높은 zIndex를 가진 레이어가 먼저 이벤트 처리
- * - **전역 이벤트 관리**: 지도 전체의 클릭/호버 이벤트를 중앙에서 관리
- * - **다중 레이어 상호작용**: 여러 레이어 간의 이벤트 충돌 방지
- * - **상호작용 비활성화 지원**: disableInteraction prop 지원
- *
- * ## 사용 방법
- * ```tsx
- * <KonvaMarkerProvider>
- *   <WoongCanvasLayer zIndex={1} ... />
- *   <WoongCanvasLayer zIndex={2} ... />
- * </KonvaMarkerProvider>
- * ```
- *
- * @version 2.2.1
- * @since 2.0.0
- * @author 박건웅
- */
-/**
- * WoongCanvasLayer 컴포넌트 인스턴스 인터페이스
- *
- * Context에서 관리하는 각 WoongCanvasLayer 인스턴스가 구현해야 하는 메서드들입니다.
- *
- * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * 용도:
+ * - zIndex 기반 이벤트 우선순위 처리
+ * - 전역 클릭/호버 이벤트 조정
+ * - 여러 레이어 간 상호작용 관리
  */
 export interface ComponentInstance<T> {
-    /** 레이어 순서 (높을수록 우선순위 높음) */
     zIndex: number;
-    /** 특정 좌표에서 히트 테스트 수행 */
     hitTest: (offset: Offset) => boolean;
-    /** 클릭 이벤트 핸들러 */
     onClick?: (payload: KonvaCanvasData<T>, selectedIds: Set<string>) => void;
-    /** 마우스 오버 이벤트 핸들러 */
     onMouseOver?: (payload: KonvaCanvasData<T>) => void;
-    /** 마우스 아웃 이벤트 핸들러 */
     onMouseOut?: (payload: KonvaCanvasData<T>) => void;
-    /** 특정 좌표에서 데이터 찾기 */
     findData: (offset: Offset) => KonvaCanvasData<T> | null;
-    /** 호버 상태 설정 */
     setHovered: (data: KonvaCanvasData<T> | null) => void;
-    /** 로컬 클릭 처리 */
     handleLocalClick: (data: KonvaCanvasData<T>) => void;
-    /** 선택된 항목 ID 목록 반환 */
     getSelectedIds: () => Set<string>;
-    /** 상호작용 비활성화 여부 체크 */
     isInteractionDisabled: () => boolean;
 }
-/**
- * KonvaMarkerContext의 값 타입
- */
 interface KonvaMarkerContextValue {
-    /** 컴포넌트 인스턴스 등록 */
     registerComponent: <T>(instance: ComponentInstance<T>) => void;
-    /** 컴포넌트 인스턴스 등록 해제 */
     unregisterComponent: <T>(instance: ComponentInstance<T>) => void;
 }
-/**
- * 다중 WoongCanvasLayer 관리를 위한 Context Provider
- *
- * 여러 개의 WoongCanvasLayer가 동시에 사용될 때 이벤트 우선순위를 관리하고
- * 전역 클릭/호버 이벤트를 조정합니다.
- *
- * @param children - Provider로 감쌀 React 컴포넌트들
- * @returns Context Provider 컴포넌트
- *
- * @example
- * ```tsx
- * <KonvaMarkerProvider>
- *   <WoongCanvasLayer zIndex={1} data={markers1} ... />
- *   <WoongCanvasLayer zIndex={2} data={markers2} ... />
- * </KonvaMarkerProvider>
- * ```
- */
 export declare const KonvaMarkerProvider: React.FC<{
     children: React.ReactNode;
 }>;
-/**
- * KonvaMarkerContext를 사용하기 위한 Hook
- *
- * @returns Context 값 또는 null (Provider 외부에서 사용 시)
- *
- * @example
- * ```tsx
- * const context = useKonvaMarkerContext();
- * if (context) {
- *   context.registerComponent(instance);
- * }
- * ```
- */
 export declare const useKonvaMarkerContext: () => KonvaMarkerContextValue | null;
 export {};