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

package/dist/components/mint-map/core/MintMapCore.js

@@ -9,8 +9,7 @@ var MapTypes = require('../types/MapTypes.js');
 var MintMapProvider = require('./provider/MintMapProvider.js');
 var MintMapCore_module = require('./MintMapCore.module.scss.js');
 require('./advanced/woongCanvas/shared/types.js');
-require('../types/MapDrawables.js');
-require('../types/MapEventTypes.js');
+require('./advanced/woongCanvas/shared/utils.js');
 var context = require('./advanced/woongCanvas/shared/context.js');
 require('./advanced/woongCanvas/shared/performance.js');
 

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

@@ -7,8 +7,8 @@ export type { KonvaCanvasMarkerOption, Paths, KonvaCanvasMarkerData, CustomRende
  * 공통 Props (MARKER와 POLYGON 모두 사용)
  */
 interface WoongCanvasLayerBaseProps<T> extends Pick<MarkerOptions, 'zIndex' | 'anchor' | 'visible'> {
-    /** 렌더링할 마커 데이터 배열 */
-    markers: KonvaCanvasMarkerData<T>[];
+    /** 렌더링할 데이터 배열 (마커 또는 폴리곤) */
+    data: KonvaCanvasMarkerData<T>[];
     /** 마커 클릭 시 호출되는 콜백 (선택) */
     onClick?: (payload: KonvaCanvasMarkerData<T>, selectedIds: Set<string>) => void;
     /** 마커에 마우스 오버 시 호출되는 콜백 (선택) */
@@ -81,13 +81,82 @@ interface WoongCanvasLayerPropsForPolygon<T> extends WoongCanvasLayerBaseProps<T
  */
 export declare type WoongCanvasLayerProps<T> = WoongCanvasLayerPropsForMarker<T> | WoongCanvasLayerPropsForPolygon<T>;
 /**
- * 🔥 React.memo 최적화: 마커 배열과 selectedItems 변경 체크
+ * 🚀 WoongCanvasLayer - Konva 기반 초고성능 마커/폴리곤 렌더링 컴포넌트
  *
- * 비교 전략:
- * 1. markers 배열 비교
- * 2. selectedItems 배열 비교 (외부 제어)
+ * ## 📌 주요 특징
+ * - **30,000개 이상의 폴리곤/마커를 60fps로 렌더링**
+ * - **Multi-Layer 아키텍처**: Base/Animation/Event 레이어 분리
+ * - **Spatial Hash Grid**: O(1) 수준의 빠른 Hit Test
+ * - **LRU 캐시**: 좌표 변환 결과 캐싱으로 성능 최적화
+ * - **Viewport Culling**: 화면에 보이는 영역만 렌더링
+ * - **Discriminated Union Props**: 타입 안전한 MARKER/POLYGON 모드
  *
- * 주의: JSON.stringify() 사용 금지! (매우 느림)
+ * ## 🎯 사용 방법
+ *
+ * ### 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}
+ * />
+ * ```
+ *
+ * ## 📊 데이터 형식
+ * ```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
+ *   }
+ * ];
+ * ```
+ *
+ * ## ⚡ 성능 최적화 팁
+ * 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} 전체 문서
  */
 declare const WoongCanvasLayer: <T>(props: WoongCanvasLayerProps<T>) => React.ReactPortal;
 export default WoongCanvasLayer;

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

@@ -24,20 +24,8 @@ var Konva__default = /*#__PURE__*/_interopDefaultLegacy(Konva);
 // 메인 컴포넌트
 // ============================================================================
 
-/**
- * Konva 기반 고성능 마커/폴리곤 렌더링 컴포넌트
- *
- * 특징:
- * - Base/Event 레이어 분리로 성능 최적화
- * - LRU 캐시로 좌표 변환 결과 캐싱
- * - Spatial Hash Grid로 빠른 Hit Test
- * - Viewport Culling으로 보이는 영역만 렌더링
- *
- * @template T 마커 데이터의 추가 속성 타입
- */
-
 var WoongCanvasLayerComponent = function (props) {
-  var markers = props.markers,
+  var data = props.data,
       dataType = props.dataType,
       onClick = props.onClick,
       onMouseOver = props.onMouseOver,
@@ -56,7 +44,7 @@ var WoongCanvasLayerComponent = function (props) {
       externalSelectedItem = props.selectedItem,
       _f = props.disableInteraction,
       disableInteraction = _f === void 0 ? false : _f,
-      options = tslib.__rest(props, ["markers", "dataType", "onClick", "onMouseOver", "onMouseOut", "enableMultiSelect", "topOnHover", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction"]); // --------------------------------------------------------------------------
+      options = tslib.__rest(props, ["data", "dataType", "onClick", "onMouseOver", "onMouseOut", "enableMultiSelect", "topOnHover", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction"]); // --------------------------------------------------------------------------
   // Hooks & Context
   // --------------------------------------------------------------------------
 
@@ -81,9 +69,9 @@ var WoongCanvasLayerComponent = function (props) {
   // Data Refs - 선택 및 Hover 상태 관리
   // --------------------------------------------------------------------------
 
-  /** markers prop을 ref로 추적 (stale closure 방지, useEffect에서 동기화) */
+  /** data prop을 ref로 추적 (stale closure 방지, useEffect에서 동기화) */
 
-  var markersRef = React.useRef(markers); // --------------------------------------------------------------------------
+  var markersRef = React.useRef(data); // --------------------------------------------------------------------------
   // State Refs - 선택 및 Hover 상태 관리
   // --------------------------------------------------------------------------
 
@@ -255,6 +243,7 @@ var WoongCanvasLayerComponent = function (props) {
   };
   /**
    * 마커 좌표 변환 결과를 캐시하고 반환
+   *
    * @param markerData 마커 데이터
    * @returns 변환된 좌표 또는 null
    */
@@ -725,11 +714,11 @@ var WoongCanvasLayerComponent = function (props) {
 
     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);
@@ -1006,13 +995,13 @@ var WoongCanvasLayerComponent = function (props) {
 
     doRenderEvent();
   }, [externalSelectedItem]); // --------------------------------------------------------------------------
-  // Lifecycle: 마커 데이터 변경 시 렌더링
+  // Lifecycle: 데이터 변경 시 렌더링
   // --------------------------------------------------------------------------
 
   React.useEffect(function () {
     if (!stageRef.current) return; // markersRef 동기화
 
-    markersRef.current = markers; // 데이터 변경 시 즉시 transform 제거 및 캐시 정리 (겹침 방지)
+    markersRef.current = data; // 데이터 변경 시 즉시 transform 제거 및 캐시 정리 (겹침 방지)
 
     if (containerRef.current) {
       containerRef.current.style.transform = '';
@@ -1029,18 +1018,18 @@ var WoongCanvasLayerComponent = function (props) {
     /**
      * 선택 상태 동기화 (최적화 버전)
      *
-     * 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();
@@ -1063,7 +1052,7 @@ var WoongCanvasLayerComponent = function (props) {
     selectedItemsMapRef.current = newSelectedItemsMap; // 즉시 렌더링
 
     renderAllImmediate();
-  }, [markers]);
+  }, [data]);
   return reactDom.createPortal(React__default["default"].createElement("div", {
     ref: containerRef,
     style: {
@@ -1074,27 +1063,96 @@ var WoongCanvasLayerComponent = function (props) {
   }), 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}
+ * />
+ * ```
+ *
+ * ## 📊 데이터 형식
+ * ```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
+ *   }
+ * ];
+ * ```
  *
- * 비교 전략:
- * 1. markers 배열 비교
- * 2. selectedItems 배열 비교 (외부 제어)
+ * ## ⚡ 성능 최적화 팁
+ * 1. **동적 boxWidth 계산**: `measureText()`로 실제 너비 계산 후 전달
+ * 2. **enableViewportCulling**: 대량 데이터 시 필수 (기본 true)
+ * 3. **selectedItems 외부 관리**: 상태를 외부에서 관리하여 리렌더링 최소화
+ * 4. **React.memo 최적화**: 컴포넌트가 자동으로 불필요한 리렌더링 방지
  *
- * 주의: JSON.stringify() 사용 금지! (매우 느림)
+ * @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 WoongCanvasLayer = React__default["default"].memo(WoongCanvasLayerComponent, function (prevProps, nextProps) {
-  // 1. markers 비교
-  var prevMarkers = prevProps.markers;
-  var nextMarkers = nextProps.markers; // 참조가 같으면 스킵
+  // 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; // 변경됨 → 리렌더링
       }
     }
@@ -1109,18 +1167,6 @@ var WoongCanvasLayer = React__default["default"].memo(WoongCanvasLayerComponent,
     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; // 변경됨 → 리렌더링
   }

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

@@ -40,10 +40,104 @@ export interface KonvaCanvasMarkerOption {
  */
 export declare type KonvaCanvasMarkerData<T = {}> = T & KonvaCanvasMarkerOption;
 /**
- * 렌더링 유틸리티 함수들
+ * 🛠️ 렌더링 유틸리티 함수들
+ *
+ * WoongCanvasLayer가 제공하는 헬퍼 함수 모음입니다.
+ * 커스텀 렌더링 함수 내에서 좌표 변환 시 사용하세요.
+ *
+ * ## 주요 기능
+ * - **자동 캐싱**: 좌표 변환 결과를 LRU 캐시에 저장 (성능 최적화)
+ * - **지도 좌표 → 화면 좌표**: 위경도를 픽셀 좌표로 자동 변환
+ * - **null 안전성**: 변환 실패 시 null 반환 (안전한 예외 처리)
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ *
+ * @example
+ * // 마커 렌더링 예시
+ * const renderBase = ({ ctx, items, utils }) => {
+ *   for (const item of items) {
+ *     const offset = utils.getOrComputeMarkerOffset(item);
+ *     if (!offset) continue; // 변환 실패 시 스킵
+ *
+ *     ctx.fillRect(offset.x, offset.y, 50, 50);
+ *   }
+ * };
+ *
+ * @example
+ * // 폴리곤 렌더링 예시
+ * const renderBase = ({ ctx, items, utils }) => {
+ *   for (const item of items) {
+ *     const offsets = utils.getOrComputePolygonOffsets(item);
+ *     if (!offsets) continue;
+ *
+ *     for (const multiPolygon of offsets) {
+ *       for (const polygon of multiPolygon) {
+ *         ctx.beginPath();
+ *         ctx.moveTo(polygon[0][0], polygon[0][1]);
+ *         for (let i = 1; i < polygon.length; i++) {
+ *           ctx.lineTo(polygon[i][0], polygon[i][1]);
+ *         }
+ *         ctx.closePath();
+ *         ctx.fill();
+ *       }
+ *     }
+ *   }
+ * };
  */
 export interface RenderUtils<T> {
+    /**
+     * 폴리곤의 위경도 좌표를 화면 픽셀 좌표로 변환합니다.
+     *
+     * - **자동 캐싱**: 동일한 폴리곤은 캐시에서 즉시 반환 (성능 최적화)
+     * - **MultiPolygon 지원**: GeoJSON MultiPolygon 형식 지원
+     * - **Donut Polygon 지원**: 구멍이 있는 폴리곤 지원
+     *
+     * @param polygonData 폴리곤 데이터 (paths 필드 필수)
+     * @returns 변환된 픽셀 좌표 배열 (4차원 배열) 또는 null (변환 실패 시)
+     *
+     * @example
+     * const offsets = utils.getOrComputePolygonOffsets(polygonItem);
+     * if (!offsets) return; // 변환 실패
+     *
+     * // offsets 구조: [MultiPolygon][Polygon][Point][x/y]
+     * for (const multiPolygon of offsets) {
+     *   for (const polygon of multiPolygon) {
+     *     ctx.beginPath();
+     *     ctx.moveTo(polygon[0][0], polygon[0][1]);
+     *     for (let i = 1; i < polygon.length; i++) {
+     *       ctx.lineTo(polygon[i][0], polygon[i][1]);
+     *     }
+     *     ctx.closePath();
+     *     ctx.fill();
+     *   }
+     * }
+     */
     getOrComputePolygonOffsets: (polygonData: KonvaCanvasMarkerData<T>) => number[][][][] | null;
+    /**
+     * 마커의 위경도 좌표를 화면 픽셀 좌표로 변환합니다.
+     *
+     * - **자동 캐싱**: 동일한 마커는 캐시에서 즉시 반환 (성능 최적화)
+     * - **중심점 기준**: 반환된 좌표는 마커의 중심점 (x, y)
+     *
+     * @param markerData 마커 데이터 (position 필드 필수)
+     * @returns 변환된 픽셀 좌표 { x, y } 또는 null (변환 실패 시)
+     *
+     * @example
+     * const offset = utils.getOrComputeMarkerOffset(markerItem);
+     * if (!offset) return; // 변환 실패
+     *
+     * // offset.x, offset.y는 화면 픽셀 좌표
+     * const boxWidth = markerItem.boxWidth || 60;
+     * const boxHeight = markerItem.boxHeight || 75;
+     *
+     * // 중앙 정렬, 하단 기준으로 그리기
+     * ctx.fillRect(
+     *   offset.x - boxWidth / 2,
+     *   offset.y - boxHeight,
+     *   boxWidth,
+     *   boxHeight
+     * );
+     */
     getOrComputeMarkerOffset: (markerData: KonvaCanvasMarkerData<T>) => Offset | null;
 }
 /**

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

@@ -30,3 +30,19 @@ export declare const isPointInPolygonData: (clickedOffset: Offset, polygonData:
  */
 export declare const isPointInMarkerData: (clickedOffset: Offset, markerData: KonvaCanvasMarkerData<any>, getMarkerOffset: (data: KonvaCanvasMarkerData<any>) => Offset | null) => boolean;
 export declare const hexToRgba: (hexColor: string, alpha?: number) => string;
+/**
+ * 텍스트 박스의 너비를 계산합니다.
+ *
+ * @param {Object} params - 파라미터 객체
+ * @param {string} params.text - 측정할 텍스트
+ * @param {string} params.fontConfig - 폰트 설정 (예: 'bold 16px Arial')
+ * @param {number} params.padding - 텍스트 박스에 적용할 패딩 값
+ * @param {number} params.minWidth - 최소 너비
+ * @returns {number} 계산된 텍스트 박스의 너비
+ */
+export declare const calculateTextBoxWidth: ({ text, fontConfig, padding, minWidth, }: {
+    text: string;
+    fontConfig: string;
+    padding: number;
+    minWidth: number;
+}) => number;

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

@@ -173,7 +173,31 @@ var hexToRgba = function (hexColor, 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);
+};
 
+exports.calculateTextBoxWidth = calculateTextBoxWidth;
 exports.computeMarkerOffset = computeMarkerOffset;
 exports.computePolygonOffsets = computePolygonOffsets;
 exports.hexToRgba = hexToRgba;

package/dist/components/mint-map/google/GoogleMintMapController.js

@@ -22,6 +22,7 @@ require('../core/advanced/canvas/CanvasMarkerClaude.js');
 require('../core/advanced/MapLoadingComponents.js');
 require('../core/advanced/woongCanvas/WoongCanvasLayer.js');
 require('../core/advanced/woongCanvas/shared/types.js');
+require('../core/advanced/woongCanvas/shared/utils.js');
 require('../core/advanced/woongCanvas/shared/context.js');
 require('../core/advanced/woongCanvas/shared/performance.js');
 require('../core/wrapper/MapControlWrapper.js');

package/dist/components/mint-map/kakao/KakaoMintMapController.js

@@ -23,6 +23,7 @@ require('../core/advanced/canvas/CanvasMarkerClaude.js');
 require('../core/advanced/MapLoadingComponents.js');
 require('../core/advanced/woongCanvas/WoongCanvasLayer.js');
 require('../core/advanced/woongCanvas/shared/types.js');
+require('../core/advanced/woongCanvas/shared/utils.js');
 require('../core/advanced/woongCanvas/shared/context.js');
 require('../core/advanced/woongCanvas/shared/performance.js');
 require('../core/wrapper/MapControlWrapper.js');

package/dist/components/mint-map/naver/NaverMintMapController.js

@@ -22,6 +22,7 @@ require('../core/advanced/canvas/CanvasMarkerClaude.js');
 require('../core/advanced/MapLoadingComponents.js');
 require('../core/advanced/woongCanvas/WoongCanvasLayer.js');
 require('../core/advanced/woongCanvas/shared/types.js');
+require('../core/advanced/woongCanvas/shared/utils.js');
 require('../core/advanced/woongCanvas/shared/context.js');
 require('../core/advanced/woongCanvas/shared/performance.js');
 require('../core/wrapper/MapControlWrapper.js');

package/dist/index.es.js

@@ -961,6 +961,29 @@ var hexToRgba = function (hexColor, 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) {
@@ -5613,20 +5636,8 @@ var renderPolygonEvent = function (selectedFillColor, selectedStrokeColor, selec
 // 메인 컴포넌트
 // ============================================================================
 
-/**
- * Konva 기반 고성능 마커/폴리곤 렌더링 컴포넌트
- *
- * 특징:
- * - Base/Event 레이어 분리로 성능 최적화
- * - LRU 캐시로 좌표 변환 결과 캐싱
- * - Spatial Hash Grid로 빠른 Hit Test
- * - Viewport Culling으로 보이는 영역만 렌더링
- *
- * @template T 마커 데이터의 추가 속성 타입
- */
-
 var WoongCanvasLayerComponent = function (props) {
-  var markers = props.markers,
+  var data = props.data,
       dataType = props.dataType,
       onClick = props.onClick,
       onMouseOver = props.onMouseOver,
@@ -5645,7 +5656,7 @@ var WoongCanvasLayerComponent = function (props) {
       externalSelectedItem = props.selectedItem,
       _f = props.disableInteraction,
       disableInteraction = _f === void 0 ? false : _f,
-      options = __rest(props, ["markers", "dataType", "onClick", "onMouseOver", "onMouseOut", "enableMultiSelect", "topOnHover", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction"]); // --------------------------------------------------------------------------
+      options = __rest(props, ["data", "dataType", "onClick", "onMouseOver", "onMouseOut", "enableMultiSelect", "topOnHover", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction"]); // --------------------------------------------------------------------------
   // Hooks & Context
   // --------------------------------------------------------------------------
 
@@ -5670,9 +5681,9 @@ var WoongCanvasLayerComponent = function (props) {
   // 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 상태 관리
   // --------------------------------------------------------------------------
 
@@ -5844,6 +5855,7 @@ var WoongCanvasLayerComponent = function (props) {
   };
   /**
    * 마커 좌표 변환 결과를 캐시하고 반환
+   *
    * @param markerData 마커 데이터
    * @returns 변환된 좌표 또는 null
    */
@@ -6314,11 +6326,11 @@ var WoongCanvasLayerComponent = function (props) {
 
     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);
@@ -6595,13 +6607,13 @@ var WoongCanvasLayerComponent = function (props) {
 
     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 = '';
@@ -6618,18 +6630,18 @@ var WoongCanvasLayerComponent = function (props) {
     /**
      * 선택 상태 동기화 (최적화 버전)
      *
-     * 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();
@@ -6652,7 +6664,7 @@ var WoongCanvasLayerComponent = function (props) {
     selectedItemsMapRef.current = newSelectedItemsMap; // 즉시 렌더링
 
     renderAllImmediate();
-  }, [markers]);
+  }, [data]);
   return createPortal(React.createElement("div", {
     ref: containerRef,
     style: {
@@ -6663,27 +6675,96 @@ var WoongCanvasLayerComponent = function (props) {
   }), 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}
+ * />
+ * ```
  *
- * 비교 전략:
- * 1. markers 배열 비교
- * 2. selectedItems 배열 비교 (외부 제어)
+ * ### 2️⃣ MARKER 모드 (커스텀 렌더링)
+ * ```tsx
+ * <WoongCanvasLayer
+ *   dataType={CanvasDataType.MARKER}
+ *   data={markers}
+ *   renderBase={renderMarkerBase}              // required
+ *   renderAnimation={renderMarkerAnimation}    // optional
+ *   renderEvent={renderMarkerEvent}            // optional
+ *   topOnHover={true}
+ *   onClick={handleClick}
+ * />
+ * ```
  *
- * 주의: JSON.stringify() 사용 금지! (매우 느림)
+ * ## 📊 데이터 형식
+ * ```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
+ *   }
+ * ];
+ * ```
+ *
+ * ## ⚡ 성능 최적화 팁
+ * 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 WoongCanvasLayer = React.memo(WoongCanvasLayerComponent, function (prevProps, nextProps) {
-  // 1. markers 비교
-  var prevMarkers = prevProps.markers;
-  var nextMarkers = nextProps.markers; // 참조가 같으면 스킵
+  // 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; // 변경됨 → 리렌더링
       }
     }
@@ -6698,18 +6779,6 @@ var WoongCanvasLayer = React.memo(WoongCanvasLayerComponent, 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; // 변경됨 → 리렌더링
   }
@@ -9548,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, WoongCanvasLayer, computeMarkerOffset, computePolygonOffsets, getClusterInfo, getMapOfType, hexToRgba, 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 };

package/dist/index.js

@@ -65,6 +65,7 @@ Object.defineProperty(exports, 'CanvasDataType', {
 	enumerable: true,
 	get: function () { return types.CanvasDataType; }
 });
+exports.calculateTextBoxWidth = utils.calculateTextBoxWidth;
 exports.computeMarkerOffset = utils.computeMarkerOffset;
 exports.computePolygonOffsets = utils.computePolygonOffsets;
 exports.hexToRgba = utils.hexToRgba;

package/dist/index.umd.js

@@ -965,6 +965,29 @@
 
     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 = React.createContext(null);
   var KonvaMarkerProvider = function (_a) {
@@ -5617,20 +5640,8 @@
   // 메인 컴포넌트
   // ============================================================================
 
-  /**
-   * Konva 기반 고성능 마커/폴리곤 렌더링 컴포넌트
-   *
-   * 특징:
-   * - Base/Event 레이어 분리로 성능 최적화
-   * - LRU 캐시로 좌표 변환 결과 캐싱
-   * - Spatial Hash Grid로 빠른 Hit Test
-   * - Viewport Culling으로 보이는 영역만 렌더링
-   *
-   * @template T 마커 데이터의 추가 속성 타입
-   */
-
   var WoongCanvasLayerComponent = function (props) {
-    var markers = props.markers,
+    var data = props.data,
         dataType = props.dataType,
         onClick = props.onClick,
         onMouseOver = props.onMouseOver,
@@ -5649,7 +5660,7 @@
         externalSelectedItem = props.selectedItem,
         _f = props.disableInteraction,
         disableInteraction = _f === void 0 ? false : _f,
-        options = tslib.__rest(props, ["markers", "dataType", "onClick", "onMouseOver", "onMouseOut", "enableMultiSelect", "topOnHover", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction"]); // --------------------------------------------------------------------------
+        options = tslib.__rest(props, ["data", "dataType", "onClick", "onMouseOver", "onMouseOut", "enableMultiSelect", "topOnHover", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction"]); // --------------------------------------------------------------------------
     // Hooks & Context
     // --------------------------------------------------------------------------
 
@@ -5674,9 +5685,9 @@
     // Data Refs - 선택 및 Hover 상태 관리
     // --------------------------------------------------------------------------
 
-    /** markers prop을 ref로 추적 (stale closure 방지, useEffect에서 동기화) */
+    /** data prop을 ref로 추적 (stale closure 방지, useEffect에서 동기화) */
 
-    var markersRef = React.useRef(markers); // --------------------------------------------------------------------------
+    var markersRef = React.useRef(data); // --------------------------------------------------------------------------
     // State Refs - 선택 및 Hover 상태 관리
     // --------------------------------------------------------------------------
 
@@ -5848,6 +5859,7 @@
     };
     /**
      * 마커 좌표 변환 결과를 캐시하고 반환
+     *
      * @param markerData 마커 데이터
      * @returns 변환된 좌표 또는 null
      */
@@ -6318,11 +6330,11 @@
 
       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);
@@ -6599,13 +6611,13 @@
 
       doRenderEvent();
     }, [externalSelectedItem]); // --------------------------------------------------------------------------
-    // Lifecycle: 마커 데이터 변경 시 렌더링
+    // Lifecycle: 데이터 변경 시 렌더링
     // --------------------------------------------------------------------------
 
     React.useEffect(function () {
       if (!stageRef.current) return; // markersRef 동기화
 
-      markersRef.current = markers; // 데이터 변경 시 즉시 transform 제거 및 캐시 정리 (겹침 방지)
+      markersRef.current = data; // 데이터 변경 시 즉시 transform 제거 및 캐시 정리 (겹침 방지)
 
       if (containerRef.current) {
         containerRef.current.style.transform = '';
@@ -6622,18 +6634,18 @@
       /**
        * 선택 상태 동기화 (최적화 버전)
        *
-       * 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();
@@ -6656,7 +6668,7 @@
       selectedItemsMapRef.current = newSelectedItemsMap; // 즉시 렌더링
 
       renderAllImmediate();
-    }, [markers]);
+    }, [data]);
     return reactDom.createPortal(React__default["default"].createElement("div", {
       ref: containerRef,
       style: {
@@ -6667,27 +6679,96 @@
     }), 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}
+   * />
+   * ```
    *
-   * 비교 전략:
-   * 1. markers 배열 비교
-   * 2. selectedItems 배열 비교 (외부 제어)
+   * ### 2️⃣ MARKER 모드 (커스텀 렌더링)
+   * ```tsx
+   * <WoongCanvasLayer
+   *   dataType={CanvasDataType.MARKER}
+   *   data={markers}
+   *   renderBase={renderMarkerBase}              // required
+   *   renderAnimation={renderMarkerAnimation}    // optional
+   *   renderEvent={renderMarkerEvent}            // optional
+   *   topOnHover={true}
+   *   onClick={handleClick}
+   * />
+   * ```
    *
-   * 주의: JSON.stringify() 사용 금지! (매우 느림)
+   * ## 📊 데이터 형식
+   * ```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
+   *   }
+   * ];
+   * ```
+   *
+   * ## ⚡ 성능 최적화 팁
+   * 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 WoongCanvasLayer = React__default["default"].memo(WoongCanvasLayerComponent, function (prevProps, nextProps) {
-    // 1. markers 비교
-    var prevMarkers = prevProps.markers;
-    var nextMarkers = nextProps.markers; // 참조가 같으면 스킵
+    // 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; // 변경됨 → 리렌더링
         }
       }
@@ -6702,18 +6783,6 @@
       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; // 변경됨 → 리렌더링
     }
@@ -9597,6 +9666,7 @@
   exports.SpatialHashGrid = SpatialHashGrid;
   exports.Status = Status;
   exports.WoongCanvasLayer = WoongCanvasLayer;
+  exports.calculateTextBoxWidth = calculateTextBoxWidth;
   exports.computeMarkerOffset = computeMarkerOffset;
   exports.computePolygonOffsets = computePolygonOffsets;
   exports.getClusterInfo = getClusterInfo;

package/package.json

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

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

@@ -1,11 +0,0 @@
-/// <reference types="react" />
-interface Cluster {
-    buildingCnt: number;
-    lat: number;
-    lng: number;
-}
-export interface ClusterMarkerProps {
-    cluster: Cluster;
-}
-declare const ClusterMarker: ({ cluster }: ClusterMarkerProps) => JSX.Element;
-export default ClusterMarker;