@mint-ui/map 1.2.0-test.10 → 1.2.0-test.12

package/dist/index.es.js

@@ -944,6 +944,46 @@ var isPointInMarkerData = function (clickedOffset, markerData, getMarkerOffset)
   var y = markerOffset.y - boxHeight - tailHeight;
   return clickedOffset.x >= x && clickedOffset.x <= x + boxWidth && clickedOffset.y >= y && clickedOffset.y <= y + boxHeight;
 };
+var hexToRgba = function (hexColor, alpha) {
+  if (alpha === void 0) {
+    alpha = 1;
+  } // NOTE: 입력된 hexColor에서 "#" 제거
+
+
+  var hex = hexColor.replace('#', ''); // NOTE: 6자리일 경우 알파 값은 사용자가 제공한 alpha 값으로 설정
+
+  if (hex.length === 6) {
+    var r = parseInt(hex.substring(0, 2), 16);
+    var g = parseInt(hex.substring(2, 4), 16);
+    var b = parseInt(hex.substring(4, 6), 16);
+    return "rgba(".concat(r, ", ").concat(g, ", ").concat(b, ", ").concat(alpha, ")");
+  }
+
+  throw new Error('Invalid hex color format');
+};
+var tempCanvas = document.createElement('canvas');
+var tempCtx = tempCanvas.getContext('2d');
+/**
+ * 텍스트 박스의 너비를 계산합니다.
+ *
+ * @param {Object} params - 파라미터 객체
+ * @param {string} params.text - 측정할 텍스트
+ * @param {string} params.fontConfig - 폰트 설정 (예: 'bold 16px Arial')
+ * @param {number} params.padding - 텍스트 박스에 적용할 패딩 값
+ * @param {number} params.minWidth - 최소 너비
+ * @returns {number} 계산된 텍스트 박스의 너비
+ */
+
+var calculateTextBoxWidth = function (_a) {
+  var text = _a.text,
+      fontConfig = _a.fontConfig,
+      padding = _a.padding,
+      minWidth = _a.minWidth;
+  if (!tempCtx) return 0;
+  tempCtx.font = fontConfig;
+  var textWidth = tempCtx.measureText(text).width;
+  return Math.max(minWidth, textWidth + padding);
+};
 
 var KonvaMarkerContext = createContext(null);
 var KonvaMarkerProvider = function (_a) {
@@ -2754,7 +2794,7 @@ function MapMarkerWrapper(_a) {
   var onMouseOverHandler = function (e) {
     var _a;
 
-    var marker = markerRef.current; //console.log('onMouseOverHandler', marker);
+    var marker = markerRef.current;
 
     if (marker) {
       var mouseOverHandler = (_a = options === null || options === void 0 ? void 0 : options.event) === null || _a === void 0 ? void 0 : _a.get('mouseover');
@@ -2767,6 +2807,25 @@ function MapMarkerWrapper(_a) {
 
       next && topOnHover && controller.markerToTheTop(marker);
     }
+  }; // 20251014 | 장한별 | mouseleave 이벤트 추가, 마우스가 마커 위에서 떠날 때 원래 zindex 를 복구하기 위함
+
+
+  var onMouseLeaveHandler = function (e) {
+    var _a;
+
+    var marker = markerRef.current;
+
+    if (marker) {
+      var mouseOutHandler = (_a = options === null || options === void 0 ? void 0 : options.event) === null || _a === void 0 ? void 0 : _a.get('mouseout');
+      var next = true;
+
+      if (mouseOutHandler) {
+        var hasNext = mouseOutHandler(e);
+        hasNext !== undefined && (next = hasNext);
+      }
+
+      next && topOnHover && controller.restoreMarkerZIndex(marker);
+    }
   }; //create object
 
 
@@ -2784,10 +2843,12 @@ function MapMarkerWrapper(_a) {
     }); //드래그 여부 초기화를 먼저 수행하기 위해 capture : true 처리
 
     divElement.addEventListener('mouseover', onMouseOverHandler);
+    divElement.addEventListener('mouseleave', onMouseLeaveHandler);
     return function () {
       divElement.removeEventListener('click', onClickHandler);
       divElement.removeEventListener('mousedown', onMousedownHandler);
       divElement.removeEventListener('mouseover', onMouseOverHandler);
+      divElement.removeEventListener('mouseleave', onMouseLeaveHandler);
 
       if (markerRef.current) {
         controller.clearDrawable(markerRef.current);
@@ -5353,45 +5414,249 @@ function LoadingImage(_a) {
   }))));
 }
 
-// 메인 컴포넌트
-// ============================================================================
+/**
+ * 폴리곤 렌더링 유틸리티
+ *
+ * 이 파일은 폴리곤 렌더링을 위한 헬퍼 함수와 팩토리 함수를 제공합니다.
+ */
 
 /**
- * Konva 기반 고성능 마커/폴리곤 렌더링 컴포넌트
+ * 폴리곤 그리기 헬퍼 함수 (도넛 폴리곤 지원)
+ */
+var drawPolygon = function (_a) {
+  var ctx = _a.ctx,
+      polygonOffsets = _a.polygonOffsets,
+      isDonutPolygon = _a.isDonutPolygon,
+      fillColor = _a.fillColor,
+      strokeColor = _a.strokeColor,
+      lineWidth = _a.lineWidth;
+
+  for (var _i = 0, polygonOffsets_1 = polygonOffsets; _i < polygonOffsets_1.length; _i++) {
+    var multiPolygon = polygonOffsets_1[_i];
+
+    if (isDonutPolygon) {
+      ctx.beginPath(); // 1. 외부 폴리곤 그리기
+
+      if (multiPolygon[0] && multiPolygon[0].length > 0) {
+        ctx.moveTo(multiPolygon[0][0][0], multiPolygon[0][0][1]);
+
+        for (var i = 1; i < multiPolygon[0].length; i++) {
+          ctx.lineTo(multiPolygon[0][i][0], multiPolygon[0][i][1]);
+        }
+
+        ctx.closePath();
+      } // 2. 내부 폴리곤 (구멍들) 그리기 - 같은 path에 추가
+
+
+      for (var j = 1; j < multiPolygon.length; j++) {
+        var innerPolygon = multiPolygon[j];
+        if (innerPolygon.length === 0) continue;
+        ctx.moveTo(innerPolygon[0][0], innerPolygon[0][1]);
+
+        for (var i = 1; i < innerPolygon.length; i++) {
+          ctx.lineTo(innerPolygon[i][0], innerPolygon[i][1]);
+        }
+
+        ctx.closePath();
+      } // 3. evenodd fill rule로 구멍 뚫기
+
+
+      ctx.fillStyle = fillColor;
+      ctx.fill('evenodd'); // 4. 외곽선 그리기
+
+      ctx.strokeStyle = strokeColor;
+      ctx.lineWidth = lineWidth;
+      ctx.stroke();
+    } else {
+      // 일반 폴리곤
+      for (var _b = 0, multiPolygon_1 = multiPolygon; _b < multiPolygon_1.length; _b++) {
+        var polygonGroup = multiPolygon_1[_b];
+        if (!polygonGroup.length) continue;
+        ctx.beginPath();
+        var firstPoint = polygonGroup[0];
+        ctx.moveTo(firstPoint[0], firstPoint[1]);
+
+        for (var i = 1; i < polygonGroup.length; i++) {
+          var point = polygonGroup[i];
+          ctx.lineTo(point[0], point[1]);
+        }
+
+        ctx.closePath();
+        ctx.fillStyle = fillColor;
+        ctx.strokeStyle = strokeColor;
+        ctx.lineWidth = lineWidth;
+        ctx.fill();
+        ctx.stroke();
+      }
+    }
+  }
+};
+/**
+ * 폴리곤 Base 렌더링 함수
  *
- * 특징:
- * - Base/Event 레이어 분리로 성능 최적화
- * - LRU 캐시로 좌표 변환 결과 캐싱
- * - Spatial Hash Grid로 빠른 Hit Test
- * - Viewport Culling으로 보이는 영역만 렌더링
+ * @param baseFillColor 기본 폴리곤 채우기 색상
+ * @param baseStrokeColor 기본 폴리곤 테두리 색상
+ * @param baseLineWidth 기본 폴리곤 테두리 두께
+ * @returns Base Layer 렌더링 함수
  *
- * @template T 마커 데이터의 추가 속성 타입
+ * @example
+ * const renderBase = renderPolygonBase(
+ *   'rgba(255, 100, 100, 0.5)',
+ *   'rgba(200, 50, 50, 0.8)',
+ *   2
+ * );
  */
 
-var WoongKonvaMarkerComponent = function (_a) {
-  var markers = _a.markers,
-      dataType = _a.dataType,
-      onClick = _a.onClick,
-      onMouseOver = _a.onMouseOver,
-      onMouseOut = _a.onMouseOut,
-      renderBase = _a.renderBase,
-      renderAnimation = _a.renderAnimation,
-      renderEvent = _a.renderEvent,
-      _b = _a.enableMultiSelect,
-      enableMultiSelect = _b === void 0 ? false : _b,
-      _c = _a.topOnHover,
-      topOnHover = _c === void 0 ? false : _c,
-      _d = _a.enableViewportCulling,
-      enableViewportCulling = _d === void 0 ? true : _d,
-      _e = _a.cullingMargin,
-      cullingMargin = _e === void 0 ? DEFAULT_CULLING_MARGIN : _e,
-      _f = _a.maxCacheSize,
-      maxCacheSize = _f === void 0 ? DEFAULT_MAX_CACHE_SIZE : _f,
-      externalSelectedItems = _a.selectedItems,
-      externalSelectedItem = _a.selectedItem,
-      _g = _a.disableInteraction,
-      disableInteraction = _g === void 0 ? false : _g,
-      options = __rest(_a, ["markers", "dataType", "onClick", "onMouseOver", "onMouseOut", "renderBase", "renderAnimation", "renderEvent", "enableMultiSelect", "topOnHover", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction"]); // --------------------------------------------------------------------------
+var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth) {
+  return function (_a) {
+    var ctx = _a.ctx,
+        items = _a.items,
+        selectedIds = _a.selectedIds,
+        utils = _a.utils;
+
+    for (var _i = 0, items_1 = items; _i < items_1.length; _i++) {
+      var item = items_1[_i]; // 선택된 항목은 Event Layer에서 그림
+
+      if (selectedIds.has(item.id)) continue;
+      if (!item.paths) continue;
+      var polygonOffsets = utils.getOrComputePolygonOffsets(item);
+      if (!polygonOffsets) continue;
+      drawPolygon({
+        ctx: ctx,
+        polygonOffsets: polygonOffsets,
+        isDonutPolygon: item.isDonutPolygon || false,
+        fillColor: baseFillColor,
+        strokeColor: baseStrokeColor,
+        lineWidth: baseLineWidth
+      });
+    }
+  };
+};
+/**
+ * 폴리곤 Event 렌더링 함수
+ *
+ * @param selectedFillColor 선택된 폴리곤 채우기 색상
+ * @param selectedStrokeColor 선택된 폴리곤 테두리 색상
+ * @param selectedLineWidth 선택된 폴리곤 테두리 두께
+ * @param activeFillColor 마지막 선택된 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+ * @param activeStrokeColor 마지막 선택된 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+ * @param activeLineWidth 마지막 선택된 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+ * @param hoveredFillColor Hover 시 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+ * @param hoveredStrokeColor Hover 시 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+ * @param hoveredLineWidth Hover 시 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+ * @returns Event Layer 렌더링 함수
+ *
+ * @example
+ * const renderEvent = renderPolygonEvent(
+ *   'rgba(255, 193, 7, 0.7)',
+ *   'rgba(255, 152, 0, 1)',
+ *   4,
+ *   'rgba(255, 0, 0, 0.8)',
+ *   undefined,
+ *   undefined,
+ *   'rgba(100, 150, 255, 0.8)'
+ * );
+ */
+
+var renderPolygonEvent = function (selectedFillColor, selectedStrokeColor, selectedLineWidth, activeFillColor, activeStrokeColor, activeLineWidth, hoveredFillColor, hoveredStrokeColor, hoveredLineWidth) {
+  // 기본값 설정 (selected 기준)
+  var _activeFillColor = activeFillColor || selectedFillColor;
+
+  var _activeStrokeColor = activeStrokeColor || selectedStrokeColor;
+
+  var _activeLineWidth = activeLineWidth || selectedLineWidth;
+
+  var _hoveredFillColor = hoveredFillColor || selectedFillColor;
+
+  var _hoveredStrokeColor = hoveredStrokeColor || selectedStrokeColor;
+
+  var _hoveredLineWidth = hoveredLineWidth || selectedLineWidth;
+
+  return function (_a) {
+    var ctx = _a.ctx,
+        hoveredItem = _a.hoveredItem,
+        utils = _a.utils,
+        selectedItems = _a.selectedItems,
+        selectedItem = _a.selectedItem; // 1. 선택된 항목들 그리기 (마지막 선택 항목과 호버된 항목 제외)
+
+    if (selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.length) {
+      for (var _i = 0, selectedItems_1 = selectedItems; _i < selectedItems_1.length; _i++) {
+        var item = selectedItems_1[_i]; // 마지막 선택 항목과 호버된 항목은 나중에 따로 그림
+
+        if (item.id === (selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.id) || (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) === item.id) continue;
+        if (!item.paths) continue;
+        var polygonOffsets = utils.getOrComputePolygonOffsets(item);
+        if (!polygonOffsets) continue;
+        drawPolygon({
+          ctx: ctx,
+          polygonOffsets: polygonOffsets,
+          isDonutPolygon: item.isDonutPolygon || false,
+          fillColor: selectedFillColor,
+          strokeColor: selectedStrokeColor,
+          lineWidth: selectedLineWidth
+        });
+      }
+    } // 2. 마지막 선택된 항목 그리기 (호버되지 않은 경우)
+
+
+    if ((selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.paths) && (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) !== selectedItem.id) {
+      var polygonOffsets = utils.getOrComputePolygonOffsets(selectedItem);
+
+      if (polygonOffsets) {
+        drawPolygon({
+          ctx: ctx,
+          polygonOffsets: polygonOffsets,
+          isDonutPolygon: selectedItem.isDonutPolygon || false,
+          fillColor: _activeFillColor,
+          strokeColor: _activeStrokeColor,
+          lineWidth: _activeLineWidth
+        });
+      }
+    } // 3. 호버된 항목 그리기 (가장 위에 표시)
+
+
+    if (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.paths) {
+      var polygonOffsets = utils.getOrComputePolygonOffsets(hoveredItem);
+      if (!polygonOffsets) return;
+      var isSelected = selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.some(function (item) {
+        return item.id === hoveredItem.id;
+      });
+      drawPolygon({
+        ctx: ctx,
+        polygonOffsets: polygonOffsets,
+        isDonutPolygon: hoveredItem.isDonutPolygon || false,
+        fillColor: isSelected ? _activeFillColor : _hoveredFillColor,
+        strokeColor: isSelected ? _activeStrokeColor : _hoveredStrokeColor,
+        lineWidth: isSelected ? _activeLineWidth : _hoveredLineWidth
+      });
+    }
+  };
+};
+
+// 메인 컴포넌트
+// ============================================================================
+
+var WoongCanvasLayerComponent = function (props) {
+  var data = props.data,
+      dataType = props.dataType,
+      onClick = props.onClick,
+      onMouseOver = props.onMouseOver,
+      onMouseOut = props.onMouseOut,
+      _a = props.enableMultiSelect,
+      enableMultiSelect = _a === void 0 ? false : _a,
+      _b = props.topOnHover,
+      topOnHover = _b === void 0 ? false : _b,
+      _c = props.enableViewportCulling,
+      enableViewportCulling = _c === void 0 ? true : _c,
+      _d = props.cullingMargin,
+      cullingMargin = _d === void 0 ? DEFAULT_CULLING_MARGIN : _d,
+      _e = props.maxCacheSize,
+      maxCacheSize = _e === void 0 ? DEFAULT_MAX_CACHE_SIZE : _e,
+      externalSelectedItems = props.selectedItems,
+      externalSelectedItem = props.selectedItem,
+      _f = props.disableInteraction,
+      disableInteraction = _f === void 0 ? false : _f,
+      options = __rest(props, ["data", "dataType", "onClick", "onMouseOver", "onMouseOut", "enableMultiSelect", "topOnHover", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction"]); // --------------------------------------------------------------------------
   // Hooks & Context
   // --------------------------------------------------------------------------
 
@@ -5416,9 +5681,9 @@ var WoongKonvaMarkerComponent = function (_a) {
   // Data Refs - 선택 및 Hover 상태 관리
   // --------------------------------------------------------------------------
 
-  /** markers prop을 ref로 추적 (stale closure 방지, useEffect에서 동기화) */
+  /** data prop을 ref로 추적 (stale closure 방지, useEffect에서 동기화) */
 
-  var markersRef = useRef(markers); // --------------------------------------------------------------------------
+  var markersRef = useRef(data); // --------------------------------------------------------------------------
   // State Refs - 선택 및 Hover 상태 관리
   // --------------------------------------------------------------------------
 
@@ -5590,6 +5855,7 @@ var WoongKonvaMarkerComponent = function (_a) {
   };
   /**
    * 마커 좌표 변환 결과를 캐시하고 반환
+   *
    * @param markerData 마커 데이터
    * @returns 변환된 좌표 또는 null
    */
@@ -5669,7 +5935,7 @@ var WoongKonvaMarkerComponent = function (_a) {
       }
     }
   }; // --------------------------------------------------------------------------
-  // 렌더링 함수
+  // 렌더링 함수 결정 (dataType에 따라)
   // --------------------------------------------------------------------------
 
   /**
@@ -5684,6 +5950,18 @@ var WoongKonvaMarkerComponent = function (_a) {
   /** Base Layer에서 사용할 빈 Set (재사용) */
 
   useRef(new Set());
+  /**
+   * 실제 사용할 렌더링 함수 결정
+   * - MARKER: 외부에서 전달받은 renderBase 사용 (필수)
+   * - POLYGON: renderer.ts의 팩토리 함수로 생성 (props 기반)
+   */
+
+  var renderBase = dataType === CanvasDataType.MARKER ? props.renderBase : renderPolygonBase(props.baseFillColor, props.baseStrokeColor, props.baseLineWidth);
+  var renderAnimation = dataType === CanvasDataType.MARKER ? props.renderAnimation : undefined;
+  var renderEvent = dataType === CanvasDataType.MARKER ? props.renderEvent : function () {
+    var polygonProps = props;
+    return renderPolygonEvent(polygonProps.selectedFillColor, polygonProps.selectedStrokeColor, polygonProps.selectedLineWidth, polygonProps.activeFillColor, polygonProps.activeStrokeColor, polygonProps.activeLineWidth, polygonProps.hoveredFillColor, polygonProps.hoveredStrokeColor, polygonProps.hoveredLineWidth);
+  }();
   /**
    * Base 레이어 렌더링 (뷰포트 컬링 적용, 선택된 마커 제외)
    *
@@ -6048,11 +6326,11 @@ var WoongKonvaMarkerComponent = function (_a) {
 
     try {
       var clickedOffset = controller.positionToOffset(event.param.position);
-      var data = findData(clickedOffset);
+      var data_1 = findData(clickedOffset);
 
-      if (data) {
-        handleLocalClick(data);
-        onClick(data, selectedIdsRef.current);
+      if (data_1) {
+        handleLocalClick(data_1);
+        onClick(data_1, selectedIdsRef.current);
       }
     } catch (error) {
       console.error('[WoongKonvaMarker] handleClick error:', error);
@@ -6329,13 +6607,13 @@ var WoongKonvaMarkerComponent = function (_a) {
 
     doRenderEvent();
   }, [externalSelectedItem]); // --------------------------------------------------------------------------
-  // Lifecycle: 마커 데이터 변경 시 렌더링
+  // Lifecycle: 데이터 변경 시 렌더링
   // --------------------------------------------------------------------------
 
   useEffect(function () {
     if (!stageRef.current) return; // markersRef 동기화
 
-    markersRef.current = markers; // 데이터 변경 시 즉시 transform 제거 및 캐시 정리 (겹침 방지)
+    markersRef.current = data; // 데이터 변경 시 즉시 transform 제거 및 캐시 정리 (겹침 방지)
 
     if (containerRef.current) {
       containerRef.current.style.transform = '';
@@ -6352,18 +6630,18 @@ var WoongKonvaMarkerComponent = function (_a) {
     /**
      * 선택 상태 동기화 (최적화 버전)
      *
-     * markers가 변경되면 selectedItemsMapRef도 업데이트 필요
+     * data가 변경되면 selectedItemsMapRef도 업데이트 필요
      * (참조가 바뀌므로 기존 Map의 데이터는 stale 상태)
      *
-     * 🔥 중요: 화면 밖 마커도 선택 상태 유지!
-     * - 현재 markers에 있으면 최신 데이터로 업데이트
+     * 🔥 중요: 화면 밖 데이터도 선택 상태 유지!
+     * - 현재 data에 있으면 최신 데이터로 업데이트
      * - 없으면 기존 selectedItemsMapRef의 데이터 유지
      *
-     * 최적화: markers를 Map으로 먼저 변환하여 find() 순회 제거
-     * - O(전체 마커 수 + 선택된 개수) - 매우 효율적
+     * 최적화: data를 Map으로 먼저 변환하여 find() 순회 제거
+     * - O(전체 데이터 수 + 선택된 개수) - 매우 효율적
      */
 
-    var markersMap = new Map(markers.map(function (m) {
+    var markersMap = new Map(data.map(function (m) {
       return [m.id, m];
     }));
     var newSelectedItemsMap = new Map();
@@ -6386,40 +6664,107 @@ var WoongKonvaMarkerComponent = function (_a) {
     selectedItemsMapRef.current = newSelectedItemsMap; // 즉시 렌더링
 
     renderAllImmediate();
-  }, [markers]);
+  }, [data]);
   return createPortal(React.createElement("div", {
     ref: containerRef,
-    style: __assign({
+    style: {
       position: 'absolute',
       width: '100%',
       height: '100%'
-    }, disableInteraction && {
-      pointerEvents: 'none'
-    })
+    }
   }), divElement);
 };
 /**
- * 🔥 React.memo 최적화: 마커 배열과 selectedItems 변경 체크
+ * 🚀 WoongCanvasLayer - Konva 기반 초고성능 마커/폴리곤 렌더링 컴포넌트
+ *
+ * ## 📌 주요 특징
+ * - **30,000개 이상의 폴리곤/마커를 60fps로 렌더링**
+ * - **Multi-Layer 아키텍처**: Base/Animation/Event 레이어 분리
+ * - **Spatial Hash Grid**: O(1) 수준의 빠른 Hit Test
+ * - **LRU 캐시**: 좌표 변환 결과 캐싱으로 성능 최적화
+ * - **Viewport Culling**: 화면에 보이는 영역만 렌더링
+ * - **Discriminated Union Props**: 타입 안전한 MARKER/POLYGON 모드
+ *
+ * ## 🎯 사용 방법
+ *
+ * ### 1️⃣ POLYGON 모드 (자동 렌더링)
+ * ```tsx
+ * <WoongCanvasLayer
+ *   dataType={CanvasDataType.POLYGON}
+ *   data={polygons}
+ *   baseFillColor="rgba(255, 100, 100, 0.5)"
+ *   baseStrokeColor="rgba(200, 50, 50, 0.8)"
+ *   baseLineWidth={2}
+ *   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
+ *   enableMultiSelect={true}
+ *   onClick={handleClick}
+ * />
+ * ```
+ *
+ * ### 2️⃣ MARKER 모드 (커스텀 렌더링)
+ * ```tsx
+ * <WoongCanvasLayer
+ *   dataType={CanvasDataType.MARKER}
+ *   data={markers}
+ *   renderBase={renderMarkerBase}              // required
+ *   renderAnimation={renderMarkerAnimation}    // optional
+ *   renderEvent={renderMarkerEvent}            // optional
+ *   topOnHover={true}
+ *   onClick={handleClick}
+ * />
+ * ```
  *
- * 비교 전략:
- * 1. markers 배열 비교
- * 2. selectedItems 배열 비교 (외부 제어)
+ * ## 📊 데이터 형식
+ * ```typescript
+ * const data: KonvaCanvasMarkerData<T>[] = [
+ *   {
+ *     id: 'unique-id',
+ *     position: new Position(lat, lng),
+ *     // POLYGON: paths 필수
+ *     paths: [[[lat, lng], [lat, lng], ...]],
+ *     // MARKER: boxWidth/boxHeight 권장 (Hit Test 정확도)
+ *     boxWidth: 60,
+ *     boxHeight: 75,
+ *     // 커스텀 데이터
+ *     ...customData
+ *   }
+ * ];
+ * ```
  *
- * 주의: JSON.stringify() 사용 금지! (매우 느림)
+ * ## ⚡ 성능 최적화 팁
+ * 1. **동적 boxWidth 계산**: `measureText()`로 실제 너비 계산 후 전달
+ * 2. **enableViewportCulling**: 대량 데이터 시 필수 (기본 true)
+ * 3. **selectedItems 외부 관리**: 상태를 외부에서 관리하여 리렌더링 최소화
+ * 4. **React.memo 최적화**: 컴포넌트가 자동으로 불필요한 리렌더링 방지
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ *
+ * @example
+ * // 동적 boxWidth 계산 예시
+ * const tempCtx = document.createElement('canvas').getContext('2d');
+ * 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} 전체 문서
  */
 
 
-var WoongKonvaMarker = React.memo(WoongKonvaMarkerComponent, function (prevProps, nextProps) {
-  // 1. markers 비교
-  var prevMarkers = prevProps.markers;
-  var nextMarkers = nextProps.markers; // 참조가 같으면 스킵
+var WoongCanvasLayer = React.memo(WoongCanvasLayerComponent, function (prevProps, nextProps) {
+  // 1. data 비교
+  var prevData = prevProps.data;
+  var nextData = nextProps.data; // 참조가 같으면 스킵
 
-  if (prevMarkers !== nextMarkers) {
+  if (prevData !== nextData) {
     // 길이가 다르면 변경됨
-    if (prevMarkers.length !== nextMarkers.length) return false; // 각 마커의 ID 비교
+    if (prevData.length !== nextData.length) return false; // 각 데이터의 ID 비교
 
-    for (var i = 0; i < prevMarkers.length; i++) {
-      if (prevMarkers[i].id !== nextMarkers[i].id) {
+    for (var i = 0; i < prevData.length; i++) {
+      if (prevData[i].id !== nextData[i].id) {
         return false; // 변경됨 → 리렌더링
       }
     }
@@ -6434,18 +6779,6 @@ var WoongKonvaMarker = React.memo(WoongKonvaMarkerComponent, function (prevProps
     return false; // 변경됨 → 리렌더링
   }
 
-  if (prevProps.onClick !== nextProps.onClick) {
-    return false; // 변경됨 → 리렌더링
-  }
-
-  if (prevProps.onMouseOver !== nextProps.onMouseOver) {
-    return false; // 변경됨 → 리렌더링
-  }
-
-  if (prevProps.onMouseOut !== nextProps.onMouseOut) {
-    return false; // 변경됨 → 리렌더링
-  }
-
   if (prevProps.disableInteraction !== nextProps.disableInteraction) {
     return false; // 변경됨 → 리렌더링
   }
@@ -7193,20 +7526,54 @@ function (_super) {
     }
   };
 
-  NaverMintMapController.prototype.setMarkerZIndex = function (marker, zIndex) {
+  NaverMintMapController.prototype.getCurrentZIndex = function (marker) {
     if (this.map && marker.element && marker.element instanceof HTMLElement) {
       var parent_1 = marker.element.parentElement;
 
-      if (parent_1) {
-        parent_1.style.zIndex = String(zIndex);
+      if (parent_1 && parent_1.style.zIndex) {
+        var zIndex = Number(parent_1.style.zIndex);
+        return isNaN(zIndex) ? undefined : zIndex;
+      }
+    }
+
+    return undefined;
+  };
+
+  NaverMintMapController.prototype.setMarkerZIndex = function (marker, zIndex) {
+    if (this.map && marker.element && marker.element instanceof HTMLElement) {
+      var parent_2 = marker.element.parentElement;
+
+      if (parent_2) {
+        parent_2.style.zIndex = String(zIndex);
       }
     }
   };
 
   NaverMintMapController.prototype.markerToTheTop = function (marker) {
+    // 이미 최상위로 올라간 상태면 (원래 zIndex가 이미 저장됨) 중복 실행 방지
+    if (this.markerOriginalZIndex !== undefined) {
+      return;
+    }
+
+    var currentZIndex = this.getCurrentZIndex(marker); // undefined면 null로 저장 (원래 zIndex가 없었음을 표시)
+
+    this.markerOriginalZIndex = currentZIndex !== undefined ? currentZIndex : null;
     this.setMarkerZIndex(marker, this.getMaxZIndex(1));
   };
 
+  NaverMintMapController.prototype.restoreMarkerZIndex = function (marker) {
+    if (this.markerOriginalZIndex !== undefined) {
+      if (this.markerOriginalZIndex === null) {
+        // 원래 zIndex가 없었으면 제거 (또는 초기값 0으로)
+        this.setMarkerZIndex(marker, 0);
+      } else {
+        this.setMarkerZIndex(marker, this.markerOriginalZIndex);
+      }
+
+      this.markerOriginalZIndex = undefined;
+    }
+  };
+
   NaverMintMapController.prototype.clearDrawable = function (drawable) {
     var _a;
 
@@ -7961,6 +8328,10 @@ function (_super) {
     }
   };
 
+  GoogleMintMapController.prototype.restoreMarkerZIndex = function (marker) {// Google Maps에서는 restoreMarkerZIndex 기능을 지원하지 않습니다.
+    // 이 기능은 Naver Maps에서만 사용 가능합니다.
+  };
+
   GoogleMintMapController.prototype.clearDrawable = function (drawable) {
     if (drawable && drawable.native) {
       if (drawable.native instanceof google.maps.Marker || drawable.native instanceof google.maps.Polygon || drawable.native instanceof google.maps.Polyline) {
@@ -8683,6 +9054,10 @@ function (_super) {
     }
   };
 
+  KakaoMintMapController.prototype.restoreMarkerZIndex = function (marker) {// Kakao Maps에서는 restoreMarkerZIndex 기능을 지원하지 않습니다.
+    // 이 기능은 Naver Maps에서만 사용 가능합니다.
+  };
+
   KakaoMintMapController.prototype.clearDrawable = function (drawable) {
     var _this = this;
 
@@ -9242,4 +9617,4 @@ function MintMap(_a) {
   }), loading));
 }
 
-export { AnimationPlayer, Bounds, CanvasDataType, CanvasMarker, CanvasMarkerClaude, CanvasMarkerHanquf, CircleMarker, DEFAULT_CULLING_MARGIN, DEFAULT_MAX_CACHE_SIZE, Drawable, GeoCalulator, GoogleMintMapController, KonvaMarkerProvider, LRUCache, MapBuildingProjection, MapCanvasMarkerWrapper, MapCanvasWrapper, MapControlWrapper, MapEvent, MapLoadingWithImage, MapMarkerWrapper, MapPolygonWrapper, MapPolylineWrapper, MapUIEvent, Marker, MintMap, MintMapCanvasRenderer, MintMapController, MintMapCore, MintMapProvider, NaverMintMapController, Offset, PointLoading, Polygon, PolygonCalculator, PolygonMarker, Polyline, Position, SPATIAL_GRID_CELL_SIZE, SVGCircle, SVGPolygon, SVGRect, Spacing, SpatialHashGrid, Status, WoongKonvaMarker, computeMarkerOffset, computePolygonOffsets, getClusterInfo, getMapOfType, isPointInMarkerData, isPointInPolygon, isPointInPolygonData, log, useKonvaMarkerContext, useMarkerMoving, useMintMapController, waiting };
+export { AnimationPlayer, Bounds, CanvasDataType, CanvasMarker, CanvasMarkerClaude, CanvasMarkerHanquf, CircleMarker, DEFAULT_CULLING_MARGIN, DEFAULT_MAX_CACHE_SIZE, Drawable, GeoCalulator, GoogleMintMapController, KonvaMarkerProvider, LRUCache, MapBuildingProjection, MapCanvasMarkerWrapper, MapCanvasWrapper, MapControlWrapper, MapEvent, MapLoadingWithImage, MapMarkerWrapper, MapPolygonWrapper, MapPolylineWrapper, MapUIEvent, Marker, MintMap, MintMapCanvasRenderer, MintMapController, MintMapCore, MintMapProvider, NaverMintMapController, Offset, PointLoading, Polygon, PolygonCalculator, PolygonMarker, Polyline, Position, SPATIAL_GRID_CELL_SIZE, SVGCircle, SVGPolygon, SVGRect, Spacing, SpatialHashGrid, Status, WoongCanvasLayer, calculateTextBoxWidth, computeMarkerOffset, computePolygonOffsets, getClusterInfo, getMapOfType, hexToRgba, isPointInMarkerData, isPointInPolygon, isPointInPolygonData, log, useKonvaMarkerContext, useMarkerMoving, useMintMapController, waiting };