@mint-ui/map 1.2.0-test.19 → 1.2.0-test.20

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

@@ -84,13 +84,54 @@ 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 테두리 두께 (선택)
  *
  * ## 🎯 사용 방법
  *
@@ -105,9 +146,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)"  // optional
- *   hoveredStrokeColor="rgba(0, 100, 200, 1)"    // optional
- *   hoveredLineWidth={3}                         // optional
+ *   hoveredFillColor="rgba(100, 150, 255, 0.8)"
+ *   hoveredStrokeColor="rgba(0, 100, 200, 1)"
+ *   hoveredLineWidth={3}
  *   enableMultiSelect={true}
  *   onClick={handleClick}
  * />
@@ -118,14 +159,35 @@ declare const WoongCanvasLayer: <T>(props: WoongCanvasLayerProps<T>) => React.Re
  * <WoongCanvasLayer
  *   dataType={CanvasDataType.MARKER}
  *   data={markers}
- *   renderBase={renderMarkerBase}              // required
- *   renderAnimation={renderMarkerAnimation}    // optional
- *   renderEvent={renderMarkerEvent}            // optional
+ *   renderBase={renderMarkerBase}
+ *   renderAnimation={renderMarkerAnimation}
+ *   renderEvent={renderMarkerEvent}
  *   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>[] = [
@@ -137,6 +199,7 @@ 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
  *   }
@@ -157,6 +220,8 @@ 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 https://github.com/your-repo/docs/WoongCanvasLayer.md} 전체 문서
+ * @see {@link ./README.md} 전체 문서
+ * @version 2.2.1
+ * @since 2.0.0
  */
 export default WoongCanvasLayer;

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

@@ -428,6 +428,12 @@ var WoongCanvasLayer = function (props) {
    * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
    * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
    * 3. 클로저로 최신 데이터 참조
+   *
+   * 🎯 topOnHover + renderEvent 조합 지원:
+   * - topOnHover가 true이고 renderEvent가 있으면:
+   *   1. 먼저 hover된 항목을 제외한 나머지 항목들 렌더링
+   *   2. 그 다음 hover된 항목을 최상단에 렌더링 (시각적 우선순위)
+   * - topOnHover가 false이거나 renderEvent가 없으면 일반 렌더링
    */
 
 
@@ -447,13 +453,41 @@ var WoongCanvasLayer = function (props) {
           var ctx = context; // 클로저로 최신 ref 값 참조
 
           var selectedItems = Array.from(selectedItemsMapRef.current.values());
-          renderEvent({
-            ctx: ctx,
-            hoveredItem: hoveredItemRef.current,
-            utils: renderUtils,
-            selectedItems: selectedItems,
-            selectedItem: selectedItemRef.current
-          });
+          var hovered = hoveredItemRef.current; // topOnHover가 true이면 hover된 항목을 최상단에 렌더링
+
+          if (topOnHover && hovered) {
+            // 1. 먼저 일반 항목들 렌더링 (hover된 항목 제외)
+            renderEvent({
+              ctx: ctx,
+              hoveredItem: null,
+              utils: renderUtils,
+              selectedItems: selectedItems.filter(function (item) {
+                return item.id !== hovered.id;
+              }),
+              selectedItem: selectedItemRef.current
+            }); // 2. hover된 항목을 최상단에 렌더링
+
+            var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
+
+            if (isHoveredInViewport) {
+              renderEvent({
+                ctx: ctx,
+                hoveredItem: hovered,
+                utils: renderUtils,
+                selectedItems: selectedItems,
+                selectedItem: selectedItemRef.current
+              });
+            }
+          } else {
+            // topOnHover가 false이거나 hover된 항목이 없으면 일반 렌더링
+            renderEvent({
+              ctx: ctx,
+              hoveredItem: hovered,
+              utils: renderUtils,
+              selectedItems: selectedItems,
+              selectedItem: selectedItemRef.current
+            });
+          }
         },
         perfectDrawEnabled: false,
         listening: false,

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

@@ -3,32 +3,49 @@ import { Position, Offset } from "../../../../types";
 /**
  * 캔버스 데이터 타입 Enum
  * 마커인지 폴리곤인지 구분하는 상수
+ *
+ * @enum {string}
+ * @memberof WoongCanvasLayer
  */
 export declare enum CanvasDataType {
+    /** 마커 타입 - 커스텀 렌더링 필요 */
     MARKER = "MARKER",
+    /** 폴리곤 타입 - 자동 렌더링 지원 */
     POLYGON = "POLYGON"
 }
 /**
- * 폴리곤 경로 정의
+ * 폴리곤 경로 정의 (GeoJSON MultiPolygon 형식)
+ *
+ * @interface Paths
+ * @memberof WoongCanvasLayer
  */
 export interface Paths {
+    /** GeoJSON 타입 (MultiPolygon) */
     type: string;
+    /** 4차원 좌표 배열 [MultiPolygon][Polygon][Point][x/y] */
     coordinates: number[][][][];
 }
-/**
- * 캔버스 마커/폴리곤 기본 옵션
- */
 /**
  * Konva 캔버스 마커/폴리곤의 기본 필수 속성
  * (렌더링에 필요한 최소 정보)
+ *
+ * @interface KonvaCanvasOption
+ * @memberof WoongCanvasLayer
  */
 export interface KonvaCanvasOption {
+    /** 고유 식별자 */
     id: string;
+    /** 지도상 위치 (위경도) */
     position: Position;
+    /** 마커 본체 너비 (Hit Test 영역) */
     boxWidth?: number;
+    /** 마커 본체 높이 (Hit Test 영역) */
     boxHeight?: number;
+    /** 마커 꼬리 높이 (Viewport Culling용, Hit Test에서는 제외) */
     tailHeight?: number;
+    /** 폴리곤 경로 (GeoJSON MultiPolygon) */
     paths?: Paths;
+    /** 도넛 폴리곤 여부 (구멍이 있는 폴리곤) */
     isDonutPolygon?: boolean;
 }
 /**

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

@@ -5,10 +5,16 @@ Object.defineProperty(exports, '__esModule', { value: true });
 /**
  * 캔버스 데이터 타입 Enum
  * 마커인지 폴리곤인지 구분하는 상수
+ *
+ * @enum {string}
+ * @memberof WoongCanvasLayer
  */
 exports.CanvasDataType = void 0;
 
 (function (CanvasDataType) {
+  /** 마커 타입 - 커스텀 렌더링 필요 */
   CanvasDataType["MARKER"] = "MARKER";
+  /** 폴리곤 타입 - 자동 렌더링 지원 */
+
   CanvasDataType["POLYGON"] = "POLYGON";
 })(exports.CanvasDataType || (exports.CanvasDataType = {}));

package/dist/index.es.js

@@ -653,11 +653,17 @@ styleInject(css_248z$1);
 /**
  * 캔버스 데이터 타입 Enum
  * 마커인지 폴리곤인지 구분하는 상수
+ *
+ * @enum {string}
+ * @memberof WoongCanvasLayer
  */
 var CanvasDataType;
 
 (function (CanvasDataType) {
+  /** 마커 타입 - 커스텀 렌더링 필요 */
   CanvasDataType["MARKER"] = "MARKER";
+  /** 폴리곤 타입 - 자동 렌더링 지원 */
+
   CanvasDataType["POLYGON"] = "POLYGON";
 })(CanvasDataType || (CanvasDataType = {}));
 
@@ -6055,6 +6061,12 @@ var WoongCanvasLayer = function (props) {
    * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
    * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
    * 3. 클로저로 최신 데이터 참조
+   *
+   * 🎯 topOnHover + renderEvent 조합 지원:
+   * - topOnHover가 true이고 renderEvent가 있으면:
+   *   1. 먼저 hover된 항목을 제외한 나머지 항목들 렌더링
+   *   2. 그 다음 hover된 항목을 최상단에 렌더링 (시각적 우선순위)
+   * - topOnHover가 false이거나 renderEvent가 없으면 일반 렌더링
    */
 
 
@@ -6074,13 +6086,41 @@ var WoongCanvasLayer = function (props) {
           var ctx = context; // 클로저로 최신 ref 값 참조
 
           var selectedItems = Array.from(selectedItemsMapRef.current.values());
-          renderEvent({
-            ctx: ctx,
-            hoveredItem: hoveredItemRef.current,
-            utils: renderUtils,
-            selectedItems: selectedItems,
-            selectedItem: selectedItemRef.current
-          });
+          var hovered = hoveredItemRef.current; // topOnHover가 true이면 hover된 항목을 최상단에 렌더링
+
+          if (topOnHover && hovered) {
+            // 1. 먼저 일반 항목들 렌더링 (hover된 항목 제외)
+            renderEvent({
+              ctx: ctx,
+              hoveredItem: null,
+              utils: renderUtils,
+              selectedItems: selectedItems.filter(function (item) {
+                return item.id !== hovered.id;
+              }),
+              selectedItem: selectedItemRef.current
+            }); // 2. hover된 항목을 최상단에 렌더링
+
+            var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
+
+            if (isHoveredInViewport) {
+              renderEvent({
+                ctx: ctx,
+                hoveredItem: hovered,
+                utils: renderUtils,
+                selectedItems: selectedItems,
+                selectedItem: selectedItemRef.current
+              });
+            }
+          } else {
+            // topOnHover가 false이거나 hover된 항목이 없으면 일반 렌더링
+            renderEvent({
+              ctx: ctx,
+              hoveredItem: hovered,
+              utils: renderUtils,
+              selectedItems: selectedItems,
+              selectedItem: selectedItemRef.current
+            });
+          }
         },
         perfectDrawEnabled: false,
         listening: false,

package/dist/index.umd.js

@@ -657,11 +657,17 @@
   /**
    * 캔버스 데이터 타입 Enum
    * 마커인지 폴리곤인지 구분하는 상수
+   *
+   * @enum {string}
+   * @memberof WoongCanvasLayer
    */
   exports.CanvasDataType = void 0;
 
   (function (CanvasDataType) {
+    /** 마커 타입 - 커스텀 렌더링 필요 */
     CanvasDataType["MARKER"] = "MARKER";
+    /** 폴리곤 타입 - 자동 렌더링 지원 */
+
     CanvasDataType["POLYGON"] = "POLYGON";
   })(exports.CanvasDataType || (exports.CanvasDataType = {}));
 
@@ -6059,6 +6065,12 @@
      * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
      * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
      * 3. 클로저로 최신 데이터 참조
+     *
+     * 🎯 topOnHover + renderEvent 조합 지원:
+     * - topOnHover가 true이고 renderEvent가 있으면:
+     *   1. 먼저 hover된 항목을 제외한 나머지 항목들 렌더링
+     *   2. 그 다음 hover된 항목을 최상단에 렌더링 (시각적 우선순위)
+     * - topOnHover가 false이거나 renderEvent가 없으면 일반 렌더링
      */
 
 
@@ -6078,13 +6090,41 @@
             var ctx = context; // 클로저로 최신 ref 값 참조
 
             var selectedItems = Array.from(selectedItemsMapRef.current.values());
-            renderEvent({
-              ctx: ctx,
-              hoveredItem: hoveredItemRef.current,
-              utils: renderUtils,
-              selectedItems: selectedItems,
-              selectedItem: selectedItemRef.current
-            });
+            var hovered = hoveredItemRef.current; // topOnHover가 true이면 hover된 항목을 최상단에 렌더링
+
+            if (topOnHover && hovered) {
+              // 1. 먼저 일반 항목들 렌더링 (hover된 항목 제외)
+              renderEvent({
+                ctx: ctx,
+                hoveredItem: null,
+                utils: renderUtils,
+                selectedItems: selectedItems.filter(function (item) {
+                  return item.id !== hovered.id;
+                }),
+                selectedItem: selectedItemRef.current
+              }); // 2. hover된 항목을 최상단에 렌더링
+
+              var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
+
+              if (isHoveredInViewport) {
+                renderEvent({
+                  ctx: ctx,
+                  hoveredItem: hovered,
+                  utils: renderUtils,
+                  selectedItems: selectedItems,
+                  selectedItem: selectedItemRef.current
+                });
+              }
+            } else {
+              // topOnHover가 false이거나 hover된 항목이 없으면 일반 렌더링
+              renderEvent({
+                ctx: ctx,
+                hoveredItem: hovered,
+                utils: renderUtils,
+                selectedItems: selectedItems,
+                selectedItem: selectedItemRef.current
+              });
+            }
           },
           perfectDrawEnabled: false,
           listening: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mint-ui/map",
-  "version": "1.2.0-test.19",
+  "version": "1.2.0-test.20",
   "main": "./dist/index.js",
   "module": "./dist/index.es.js",
   "browser": "./dist/index.umd.js",