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

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
+  // Konva Refs - Multi-Layer 아키텍처
   // --------------------------------------------------------------------------
 
   var stageRef = React.useRef(null);
   var baseLayerRef = React.useRef(null);
   var animationLayerRef = React.useRef(null);
   var eventLayerRef = React.useRef(null); // --------------------------------------------------------------------------
-  // Data Refs - 선택 및 Hover 상태 관리
+  // Data Refs - 데이터 동기화 및 상태 관리
   // --------------------------------------------------------------------------
 
   /** 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,11 +330,14 @@ 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. 클로저로 최신 데이터 참조
@@ -400,11 +403,14 @@ var WoongCanvasLayer = function (props) {
 
 
     layer.batchDraw();
-  };
+  }; // --------------------------------------------------------------------------
+  // 렌더링 함수: Animation Layer (선택된 항목 애니메이션)
+  // --------------------------------------------------------------------------
+
   /**
    * Animation 레이어 렌더링 (선택된 마커 애니메이션)
    *
-   * 🔥 최적화: sceneFunc 내부에서 최신 items 참조
+   * 🔥 성능 최적화: sceneFunc 내부에서 최신 items 참조
    * - 선택 변경 시에만 재생성
    * - 지도 이동 시에는 기존 Animation 계속 실행
    */
@@ -420,11 +426,14 @@ var WoongCanvasLayer = function (props) {
       items: dataRef.current,
       utils: renderUtils
     });
-  };
+  }; // --------------------------------------------------------------------------
+  // 렌더링 함수: Event Layer (상호작용 상태 렌더링)
+  // --------------------------------------------------------------------------
+
   /**
    * Event 레이어 렌더링 (hover + 선택 상태 표시)
    *
-   * 🔥 최적화:
+   * 🔥 성능 최적화:
    * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
    * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
    * 3. 클로저로 최신 데이터 참조
@@ -450,10 +459,11 @@ 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; // topOnHover가 true이면 hover된 항목을 최상단에 렌더링
+          var hovered = hoveredItemRef.current;
+          var selectedItem = selectedItemRef.current; // topOnHover가 true이면 hover된 항목을 최상단에 렌더링
 
           if (topOnHover && hovered) {
             // 1. 먼저 일반 항목들 렌더링 (hover된 항목 제외)
@@ -462,9 +472,9 @@ var WoongCanvasLayer = function (props) {
               hoveredItem: null,
               utils: renderUtils,
               selectedItems: selectedItems.filter(function (item) {
-                return item.id !== hovered.id;
+                return item && item.id !== hovered.id;
               }),
-              selectedItem: selectedItemRef.current
+              selectedItem: selectedItem
             }); // 2. hover된 항목을 최상단에 렌더링
 
             var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
@@ -475,7 +485,7 @@ var WoongCanvasLayer = function (props) {
                 hoveredItem: hovered,
                 utils: renderUtils,
                 selectedItems: selectedItems,
-                selectedItem: selectedItemRef.current
+                selectedItem: selectedItem
               });
             }
           } else {
@@ -485,7 +495,7 @@ var WoongCanvasLayer = function (props) {
               hoveredItem: hovered,
               utils: renderUtils,
               selectedItems: selectedItems,
-              selectedItem: selectedItemRef.current
+              selectedItem: selectedItem
             });
           }
         },
@@ -598,7 +608,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 +778,7 @@ var WoongCanvasLayer = function (props) {
     }
   };
   /**
-   * 마우스 이동 이벤트 처리 (hover 감지)
+   * 마우스 이동 이벤트 처리 (hover 감지 및 상태 업데이트)
    */
 
 
@@ -812,7 +822,7 @@ var WoongCanvasLayer = function (props) {
     controller.setMapCursor('grab');
   };
   /**
-   * 마우스가 canvas를 벗어날 때 hover cleanup
+   * 마우스가 canvas를 벗어날 때 hover 상태 정리
    */
 
 
@@ -872,7 +882,7 @@ var WoongCanvasLayer = function (props) {
       }
     }
   }, [options]); // --------------------------------------------------------------------------
-  // Lifecycle: Konva 초기화 및 이벤트 리스너 등록
+  // Lifecycle: Konva 초기화 및 이벤트 리스너 등록 (컴포넌트 마운트)
   // --------------------------------------------------------------------------
 
   React.useEffect(function () {
@@ -998,26 +1008,32 @@ 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();
-    externalSelectedItems.forEach(function (item) {
-      newSelectedIds.add(item.id);
-      newSelectedItemsMap.set(item.id, item);
-    });
+    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);
+        }
+      });
+    }
+
     selectedIdsRef.current = newSelectedIds;
     selectedItemsMapRef.current = newSelectedItemsMap; // 렌더링
 
@@ -1026,17 +1042,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; // selectedItem이 변경되면 Event Layer만 다시 그림
+    selectedItemRef.current = externalSelectedItem || null; // selectedItem이 변경되면 Event Layer만 다시 그림
 
     doRenderEvent();
   }, [externalSelectedItem]); // --------------------------------------------------------------------------
-  // Lifecycle: 데이터 변경 시 렌더링
+  // Lifecycle: 데이터 변경 시 렌더링 (데이터 동기화 및 최적화)
   // --------------------------------------------------------------------------
 
   React.useEffect(function () {
@@ -1093,7 +1109,10 @@ var WoongCanvasLayer = function (props) {
     selectedItemsMapRef.current = newSelectedItemsMap; // 즉시 렌더링
 
     renderAllImmediate();
-  }, [data]);
+  }, [data]); // --------------------------------------------------------------------------
+  // Render - React Portal을 통한 DOM 렌더링
+  // --------------------------------------------------------------------------
+
   return reactDom.createPortal(React__default["default"].createElement("div", {
     ref: containerRef,
     style: {

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

@@ -1,3 +1,13 @@
+/**
+ * @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,31 +2,99 @@ import React from "react";
 import { Offset } from "../../../../types";
 import { KonvaCanvasData } from "./types";
 /**
- * 다중 WoongKonvaMarker 인스턴스를 관리하기 위한 Context
+ * @fileoverview 다중 WoongCanvasLayer 인스턴스를 관리하기 위한 React Context
  *
- * 용도:
- * - zIndex 기반 이벤트 우선순위 처리
- * - 전역 클릭/호버 이벤트 조정
- * - 여러 레이어 간 상호작용 관리
+ * 이 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 마커/폴리곤 데이터의 추가 속성 타입
  */
 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 {};

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

@@ -9,18 +9,50 @@ function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'defau
 
 var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
 
+/** 다중 레이어 관리를 위한 React Context */
+
 var KonvaMarkerContext = React.createContext(null);
+/**
+ * 다중 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>
+ * ```
+ */
+
 var KonvaMarkerProvider = function (_a) {
   var children = _a.children;
-  var controller = MintMapProvider.useMintMapController(); // Refs
+  var controller = MintMapProvider.useMintMapController(); // === Refs ===
+
+  /** 등록된 모든 컴포넌트 인스턴스들 (zIndex 내림차순 정렬) */
 
   var componentsRef = React.useRef([]);
+  /** 현재 호버된 컴포넌트 인스턴스 */
+
   var currentHoveredRef = React.useRef(null);
+  /** 현재 호버된 데이터 */
+
   var currentHoveredDataRef = React.useRef(null);
-  var draggingRef = React.useRef(false);
+  /** 드래그/줌 중 여부 (마우스 이동 이벤트 무시용) */
+
+  var draggingRef = React.useRef(false); // === 컴포넌트 관리 함수들 ===
+
   /**
-   * 컴포넌트 등록 (zIndex 내림차순 정렬)
-   * 높은 zIndex가 먼저 처리됨
+   * 컴포넌트 인스턴스 등록
+   *
+   * zIndex 내림차순으로 정렬하여 높은 우선순위의 컴포넌트가 먼저 이벤트를 처리하도록 합니다.
+   *
+   * @param instance - 등록할 컴포넌트 인스턴스
    */
 
   var registerComponent = React.useCallback(function (instance) {
@@ -30,7 +62,12 @@ var KonvaMarkerProvider = function (_a) {
     });
   }, []);
   /**
-   * 컴포넌트 등록 해제
+   * 컴포넌트 인스턴스 등록 해제
+   *
+   * 컴포넌트가 언마운트될 때 호출되어 Context에서 제거합니다.
+   * 현재 호버 중인 컴포넌트라면 호버 상태도 초기화합니다.
+   *
+   * @param instance - 등록 해제할 컴포넌트 인스턴스
    */
 
   var unregisterComponent = React.useCallback(function (instance) {
@@ -43,9 +80,15 @@ var KonvaMarkerProvider = function (_a) {
     componentsRef.current = componentsRef.current.filter(function (c) {
       return c !== instance;
     });
-  }, []);
+  }, []); // === 전역 이벤트 핸들러들 ===
+
   /**
-   * 전역 클릭 핸들러 (zIndex 우선순위)
+   * 전역 클릭 이벤트 핸들러
+   *
+   * zIndex 우선순위에 따라 등록된 컴포넌트들을 순회하며 클릭된 데이터를 찾습니다.
+   * 첫 번째로 히트된 컴포넌트의 이벤트만 처리합니다.
+   *
+   * @param event - 지도 클릭 이벤트 파라미터
    */
 
   var handleGlobalClick = React.useCallback(function (event) {
@@ -55,7 +98,7 @@ var KonvaMarkerProvider = function (_a) {
     var clickedOffset = controller.positionToOffset(event.param.position); // zIndex 순서대로 순회 (높은 것부터)
 
     for (var _i = 0, _b = componentsRef.current; _i < _b.length; _i++) {
-      var component = _b[_i]; // 🚫 상호작용이 비활성화된 컴포넌트는 스킵
+      var component = _b[_i]; // 상호작용이 비활성화된 컴포넌트는 스킵
 
       if (component.isInteractionDisabled()) continue;
       var data = component.findData(clickedOffset);
@@ -72,7 +115,12 @@ var KonvaMarkerProvider = function (_a) {
     }
   }, [controller]);
   /**
-   * 전역 마우스 이동 핸들러 (zIndex 우선순위)
+   * 전역 마우스 이동 이벤트 핸들러
+   *
+   * zIndex 우선순위에 따라 호버된 데이터를 찾고, 호버 상태가 변경되면
+   * 이전 호버를 해제하고 새로운 호버를 설정합니다.
+   *
+   * @param event - 지도 마우스 이동 이벤트 파라미터
    */
 
   var handleGlobalMouseMove = React.useCallback(function (event) {
@@ -85,7 +133,7 @@ var KonvaMarkerProvider = function (_a) {
     var newHoveredData = null;
 
     for (var _i = 0, _b = componentsRef.current; _i < _b.length; _i++) {
-      var component = _b[_i]; // 🚫 상호작용이 비활성화된 컴포넌트는 스킵
+      var component = _b[_i]; // 상호작용이 비활성화된 컴포넌트는 스킵
 
       if (component.isInteractionDisabled()) continue;
       var data = component.findData(mouseOffset);
@@ -122,19 +170,24 @@ var KonvaMarkerProvider = function (_a) {
     }
   }, [controller]);
   /**
-   * 줌/드래그 시작 (마우스 이동 이벤트 무시)
+   * 줌/드래그 시작 이벤트 핸들러
+   *
+   * 지도가 줌이나 드래그를 시작할 때 마우스 이동 이벤트를 무시하도록 설정합니다.
+   * 이는 성능 최적화와 불필요한 호버 이벤트 방지를 위한 것입니다.
    */
 
   var handleZoomStart = React.useCallback(function () {
     draggingRef.current = true;
   }, []);
   /**
-   * 지도 idle (마우스 이동 이벤트 재개)
+   * 지도 idle 이벤트 핸들러
+   *
+   * 지도가 idle 상태가 되면 마우스 이동 이벤트를 다시 활성화합니다.
    */
 
   var handleIdle = React.useCallback(function () {
     draggingRef.current = false;
-  }, []); // 이벤트 리스너 등록
+  }, []); // === 이벤트 리스너 등록 ===
 
   React.useEffect(function () {
     controller.addEventListener('CLICK', handleGlobalClick);
@@ -147,7 +200,7 @@ var KonvaMarkerProvider = function (_a) {
       controller.removeEventListener('ZOOMSTART', handleZoomStart);
       controller.removeEventListener('IDLE', handleIdle);
     };
-  }, [controller, handleGlobalClick, handleGlobalMouseMove, handleZoomStart, handleIdle]); // Context value 메모이제이션
+  }, [controller, handleGlobalClick, handleGlobalMouseMove, handleZoomStart, handleIdle]); // === Context value 메모이제이션 ===
 
   var contextValue = React.useMemo(function () {
     return {
@@ -159,6 +212,20 @@ var KonvaMarkerProvider = function (_a) {
     value: contextValue
   }, children);
 };
+/**
+ * KonvaMarkerContext를 사용하기 위한 Hook
+ *
+ * @returns Context 값 또는 null (Provider 외부에서 사용 시)
+ *
+ * @example
+ * ```tsx
+ * const context = useKonvaMarkerContext();
+ * if (context) {
+ *   context.registerComponent(instance);
+ * }
+ * ```
+ */
+
 var useKonvaMarkerContext = function () {
   var context = React.useContext(KonvaMarkerContext);
   return context;

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

@@ -1,4 +1,15 @@
+/**
+ * @fileoverview WoongCanvasLayer의 공유 유틸리티 모듈
+ *
+ * 이 파일은 WoongCanvasLayer에서 사용하는 모든 공통 타입, 유틸리티 함수,
+ * 성능 최적화 클래스, Context Provider를 외부로 노출합니다.
+ *
+ * @version 2.2.1
+ * @since 2.0.0
+ * @author 박건웅
+ */
 export * from './types';
 export * from './utils';
 export * from './context';
 export * from './performance';
+export * from './renderer';

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

@@ -1,3 +1,18 @@
+/**
+ * @fileoverview WoongCanvasLayer 성능 최적화를 위한 상수 및 클래스
+ *
+ * 이 파일은 30,000개 이상의 마커/폴리곤을 60fps로 렌더링하기 위한
+ * 성능 최적화 상수와 최적화된 자료구조들을 제공합니다.
+ *
+ * ## 주요 구성 요소
+ * - **성능 최적화 상수**: 그리드 셀 크기, 캐시 크기, 컬링 여유 공간
+ * - **LRUCache**: 좌표 변환 결과 캐싱을 위한 LRU 캐시 구현
+ * - **SpatialHashGrid**: O(1) 수준의 빠른 Hit Test를 위한 공간 해시 그리드
+ *
+ * @version 2.2.1
+ * @since 2.0.0
+ * @author 박건웅
+ */
 /**
  * 공간 인덱스 그리드 셀 크기 (px)
  *
@@ -40,12 +55,29 @@ export declare const DEFAULT_CULLING_MARGIN = 100;
 export declare const DEFAULT_MAX_CACHE_SIZE = 30000;
 /**
  * LRU (Least Recently Used) Cache
- * 메모리 제한을 위한 캐시 구현 (최적화 버전)
  *
- * 개선 사항:
- * 1. get() 성능 향상: 접근 빈도 추적 없이 단순 조회만 수행 (delete+set 제거)
- * 2. set() 버그 수정: 기존 키 업데이트 시 maxSize 체크 로직 개선
- * 3. 메모리 효율: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
+ * 메모리 제한을 위한 캐시 구현으로, 좌표 변환 결과를 캐싱하여
+ * 성능을 최적화합니다. WoongCanvasLayer의 특성에 맞게 최적화되었습니다.
+ *
+ * ## 주요 특징
+ * - **빠른 조회**: O(1) 해시 조회로 성능 최적화
+ * - **메모리 제한**: 최대 크기 초과 시 자동 eviction
+ * - **FIFO 방식**: 삽입 순서 기반 eviction (접근 빈도 추적 없음)
+ *
+ * ## 개선 사항
+ * 1. **get() 성능 향상**: 접근 빈도 추적 없이 단순 조회만 수행
+ * 2. **set() 버그 수정**: 기존 키 업데이트 시 maxSize 체크 로직 개선
+ * 3. **메모리 효율**: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
+ *
+ * @template K 캐시 키 타입
+ * @template V 캐시 값 타입
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUCache<string, Offset>(1000);
+ * cache.set('marker-1', { x: 100, y: 200 });
+ * const offset = cache.get('marker-1'); // { x: 100, y: 200 }
+ * ```
  */
 export declare class LRUCache<K, V> {
     private cache;
@@ -81,16 +113,33 @@ export declare class LRUCache<K, V> {
 }
 /**
  * Spatial Hash Grid (공간 해시 그리드)
- * 공간 인덱싱을 위한 그리드 기반 자료구조 (개선 버전)
  *
- * 개선 사항:
- * 1. 중복 삽입 방지: 같은 항목을 여러 번 insert 해도 안전
- * 2. 메모리 누수 방지: 기존 항목 자동 제거
- * 3. 성능 최적화: 불필요한 배열 생성 최소화
+ * 공간 인덱싱을 위한 그리드 기반 자료구조로, 2D 공간을 격자로 나누어
+ * 특정 영역에 있는 객체들을 빠르게 찾을 수 있게 해줍니다.
+ *
+ * ## 주요 특징
+ * - **O(1) 조회**: 클릭 위치 주변의 객체들만 체크하여 성능 최적화
+ * - **메모리 효율**: 격자 기반으로 필요한 영역만 인덱싱
+ * - **중복 방지**: 같은 항목을 여러 번 삽입해도 안전
+ *
+ * ## 성능 비교
+ * - **일반 검색**: 30,000개 항목 전체 체크 → O(n)
+ * - **Spatial Hash**: 클릭 위치 주변 ~10개만 체크 → O(1) + O(10)
+ * - **성능 향상**: 약 3,000배 빠름! 🚀
+ *
+ * ## 개선 사항
+ * 1. **중복 삽입 방지**: 같은 항목을 여러 번 insert 해도 안전
+ * 2. **메모리 누수 방지**: 기존 항목 자동 제거
+ * 3. **성능 최적화**: 불필요한 배열 생성 최소화
+ *
+ * @template T 그리드에 저장할 객체 타입
  *
- * 사용 사례:
- * - 빠른 Hit Test (마우스 클릭 시 어떤 마커/폴리곤인지 찾기)
- * - 30,000개 항목 → 클릭 위치 주변 ~10개만 체크 (3,000배 빠름)
+ * @example
+ * ```typescript
+ * const grid = new SpatialHashGrid<Marker>(50);
+ * grid.insert(marker, { x: 100, y: 200, width: 30, height: 40 });
+ * const nearby = grid.query(105, 205, 10); // (105, 205) 주변 10px 반경
+ * ```
  */
 export declare class SpatialHashGrid<T> {
     private cellSize;