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

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

@@ -2,6 +2,21 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+/**
+ * @fileoverview WoongCanvasLayer 성능 최적화를 위한 상수 및 클래스
+ *
+ * 이 파일은 30,000개 이상의 마커/폴리곤을 60fps로 렌더링하기 위한
+ * 성능 최적화 상수와 최적화된 자료구조들을 제공합니다.
+ *
+ * ## 주요 구성 요소
+ * - **성능 최적화 상수**: 그리드 셀 크기, 캐시 크기, 컬링 여유 공간
+ * - **LRUCache**: 좌표 변환 결과 캐싱을 위한 LRU 캐시 구현
+ * - **SpatialHashGrid**: O(1) 수준의 빠른 Hit Test를 위한 공간 해시 그리드
+ *
+ * @version 2.2.1
+ * @since 2.0.0
+ * @author 박건웅
+ */
 // ============================================================================
 // 성능 최적화 상수 (30,000개 마커/폴리곤 기준 최적화)
 // ============================================================================
@@ -50,12 +65,29 @@ var DEFAULT_CULLING_MARGIN = 100;
 var 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 }
+ * ```
  */
 
 var LRUCache =
@@ -135,16 +167,33 @@ function () {
 }();
 /**
  * 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 반경
+ * ```
  */
 
 var SpatialHashGrid =

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

@@ -1,11 +1,45 @@
 /**
- * 폴리곤 렌더링 유틸리티
+ * @fileoverview 폴리곤 렌더링을 위한 유틸리티 및 팩토리 함수
  *
- * 이 파일은 폴리곤 렌더링을 위한 헬퍼 함수와 팩토리 함수를 제공합니다.
+ * 이 파일은 WoongCanvasLayer의 POLYGON 모드에서 사용하는 폴리곤 렌더링
+ * 함수들을 제공합니다. 다양한 상태(기본, 선택, 호버)에 따른 렌더링과
+ * 도넛 폴리곤(구멍이 있는 폴리곤) 지원을 포함합니다.
+ *
+ * ## 주요 기능
+ * - **폴리곤 그리기**: Canvas 2D API를 사용한 폴리곤 렌더링
+ * - **도넛 폴리곤 지원**: evenodd fill rule을 사용한 구멍 처리
+ * - **상태별 렌더링**: 기본/선택/호버 상태에 따른 색상 및 스타일 적용
+ * - **팩토리 함수**: 렌더링 함수를 쉽게 생성할 수 있는 헬퍼
+ *
+ * @version 2.2.1
+ * @since 2.0.0
+ * @author 박건웅
  */
 import { CustomRenderBase, CustomRenderEvent, KonvaCanvasData } from "./types";
 /**
- * 폴리곤 그리기 헬퍼 함수 (도넛 폴리곤 지원)
+ * 폴리곤 그리기 헬퍼 함수
+ *
+ * Canvas 2D API를 사용하여 폴리곤을 그리는 핵심 함수입니다.
+ * 도넛 폴리곤(구멍이 있는 폴리곤)도 지원합니다.
+ *
+ * @param ctx - Canvas 2D 렌더링 컨텍스트
+ * @param polygonOffsets - 변환된 폴리곤 좌표 배열
+ * @param isDonutPolygon - 도넛 폴리곤 여부
+ * @param fillColor - 채우기 색상
+ * @param strokeColor - 테두리 색상
+ * @param lineWidth - 테두리 두께
+ *
+ * @example
+ * ```typescript
+ * drawPolygon({
+ *   ctx,
+ *   polygonOffsets: [[[[100, 200], [200, 200], [200, 300], [100, 300]]]],
+ *   isDonutPolygon: false,
+ *   fillColor: 'rgba(255, 0, 0, 0.5)',
+ *   strokeColor: 'rgba(255, 0, 0, 1)',
+ *   lineWidth: 2
+ * });
+ * ```
  */
 export declare const drawPolygon: ({ ctx, polygonOffsets, isDonutPolygon, fillColor, strokeColor, lineWidth }: {
     ctx: CanvasRenderingContext2D;
@@ -16,39 +50,58 @@ export declare const drawPolygon: ({ ctx, polygonOffsets, isDonutPolygon, fillCo
     lineWidth: number;
 }) => void;
 /**
- * 폴리곤 Base 렌더링 함수
+ * 폴리곤 Base Layer 렌더링 함수 팩토리
  *
- * @param baseFillColor 기본 폴리곤 채우기 색상
- * @param baseStrokeColor 기본 폴리곤 테두리 색상
- * @param baseLineWidth 기본 폴리곤 테두리 두께
+ * 기본 상태의 폴리곤들을 렌더링하는 함수를 생성합니다.
+ * 선택된 폴리곤들은 Event Layer에서 렌더링되므로 제외됩니다.
+ *
+ * @param baseFillColor - 기본 폴리곤 채우기 색상
+ * @param baseStrokeColor - 기본 폴리곤 테두리 색상
+ * @param baseLineWidth - 기본 폴리곤 테두리 두께
  * @returns Base Layer 렌더링 함수
  *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ *
  * @example
+ * ```typescript
  * const renderBase = renderPolygonBase(
- *   'rgba(255, 100, 100, 0.5)',
- *   'rgba(200, 50, 50, 0.8)',
- *   2
+ *   'rgba(255, 100, 100, 0.5)',  // 기본 채우기 색상
+ *   'rgba(200, 50, 50, 0.8)',    // 기본 테두리 색상
+ *   2                             // 기본 테두리 두께
  * );
+ * ```
  */
 export declare const renderPolygonBase: <T = any>(baseFillColor: string, baseStrokeColor: string, baseLineWidth: number) => CustomRenderBase<KonvaCanvasData<T>>;
 /**
- * 폴리곤 Event 렌더링 함수
- *
- * @param baseFillColor 기본 폴리곤 채우기 색상 (필수, fallback용)
- * @param baseStrokeColor 기본 폴리곤 테두리 색상 (필수, fallback용)
- * @param baseLineWidth 기본 폴리곤 테두리 두께 (필수, fallback용)
- * @param selectedFillColor 선택된 폴리곤 채우기 색상 (선택, 기본값: baseFillColor)
- * @param selectedStrokeColor 선택된 폴리곤 테두리 색상 (선택, 기본값: baseStrokeColor)
- * @param selectedLineWidth 선택된 폴리곤 테두리 두께 (선택, 기본값: baseLineWidth)
- * @param activeFillColor 마지막 선택된 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
- * @param activeStrokeColor 마지막 선택된 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
- * @param activeLineWidth 마지막 선택된 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
- * @param hoveredFillColor Hover 시 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
- * @param hoveredStrokeColor Hover 시 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
- * @param hoveredLineWidth Hover 시 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+ * 폴리곤 Event Layer 렌더링 함수 팩토리
+ *
+ * 선택, 호버, 활성 상태의 폴리곤들을 렌더링하는 함수를 생성합니다.
+ * 다양한 상태에 따른 색상과 스타일을 지원하며, fallback 메커니즘을 제공합니다.
+ *
+ * ## 상태별 렌더링 우선순위
+ * 1. **Hovered**: 마우스가 올라간 폴리곤 (최우선)
+ * 2. **Active**: 마지막으로 선택된 폴리곤
+ * 3. **Selected**: 선택된 폴리곤들
+ * 4. **Base**: 기본 상태 (fallback)
+ *
+ * @param baseFillColor - 기본 폴리곤 채우기 색상 (필수, fallback용)
+ * @param baseStrokeColor - 기본 폴리곤 테두리 색상 (필수, fallback용)
+ * @param baseLineWidth - 기본 폴리곤 테두리 두께 (필수, fallback용)
+ * @param selectedFillColor - 선택된 폴리곤 채우기 색상 (선택, 기본값: baseFillColor)
+ * @param selectedStrokeColor - 선택된 폴리곤 테두리 색상 (선택, 기본값: baseStrokeColor)
+ * @param selectedLineWidth - 선택된 폴리곤 테두리 두께 (선택, 기본값: baseLineWidth)
+ * @param activeFillColor - 마지막 선택된 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+ * @param activeStrokeColor - 마지막 선택된 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+ * @param activeLineWidth - 마지막 선택된 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+ * @param hoveredFillColor - Hover 시 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+ * @param hoveredStrokeColor - Hover 시 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+ * @param hoveredLineWidth - Hover 시 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
  * @returns Event Layer 렌더링 함수
  *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ *
  * @example
+ * ```typescript
  * const renderEvent = renderPolygonEvent(
  *   'rgba(255, 100, 100, 0.5)',  // baseFillColor
  *   'rgba(200, 50, 50, 0.8)',    // baseStrokeColor
@@ -57,5 +110,6 @@ export declare const renderPolygonBase: <T = any>(baseFillColor: string, baseStr
  *   'rgba(255, 152, 0, 1)',      // selectedStrokeColor
  *   4                             // selectedLineWidth
  * );
+ * ```
  */
 export declare const renderPolygonEvent: <T = any>(baseFillColor: string, baseStrokeColor: string, baseLineWidth: number, selectedFillColor?: string, selectedStrokeColor?: string, selectedLineWidth?: number, activeFillColor?: string, activeStrokeColor?: string, activeLineWidth?: number, hoveredFillColor?: string, hoveredStrokeColor?: string, hoveredLineWidth?: number) => CustomRenderEvent<KonvaCanvasData<T>>;

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

@@ -3,13 +3,47 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 /**
- * 폴리곤 렌더링 유틸리티
+ * @fileoverview 폴리곤 렌더링을 위한 유틸리티 및 팩토리 함수
  *
- * 이 파일은 폴리곤 렌더링을 위한 헬퍼 함수와 팩토리 함수를 제공합니다.
+ * 이 파일은 WoongCanvasLayer의 POLYGON 모드에서 사용하는 폴리곤 렌더링
+ * 함수들을 제공합니다. 다양한 상태(기본, 선택, 호버)에 따른 렌더링과
+ * 도넛 폴리곤(구멍이 있는 폴리곤) 지원을 포함합니다.
+ *
+ * ## 주요 기능
+ * - **폴리곤 그리기**: Canvas 2D API를 사용한 폴리곤 렌더링
+ * - **도넛 폴리곤 지원**: evenodd fill rule을 사용한 구멍 처리
+ * - **상태별 렌더링**: 기본/선택/호버 상태에 따른 색상 및 스타일 적용
+ * - **팩토리 함수**: 렌더링 함수를 쉽게 생성할 수 있는 헬퍼
+ *
+ * @version 2.2.1
+ * @since 2.0.0
+ * @author 박건웅
  */
 
 /**
- * 폴리곤 그리기 헬퍼 함수 (도넛 폴리곤 지원)
+ * 폴리곤 그리기 헬퍼 함수
+ *
+ * Canvas 2D API를 사용하여 폴리곤을 그리는 핵심 함수입니다.
+ * 도넛 폴리곤(구멍이 있는 폴리곤)도 지원합니다.
+ *
+ * @param ctx - Canvas 2D 렌더링 컨텍스트
+ * @param polygonOffsets - 변환된 폴리곤 좌표 배열
+ * @param isDonutPolygon - 도넛 폴리곤 여부
+ * @param fillColor - 채우기 색상
+ * @param strokeColor - 테두리 색상
+ * @param lineWidth - 테두리 두께
+ *
+ * @example
+ * ```typescript
+ * drawPolygon({
+ *   ctx,
+ *   polygonOffsets: [[[[100, 200], [200, 200], [200, 300], [100, 300]]]],
+ *   isDonutPolygon: false,
+ *   fillColor: 'rgba(255, 0, 0, 0.5)',
+ *   strokeColor: 'rgba(255, 0, 0, 1)',
+ *   lineWidth: 2
+ * });
+ * ```
  */
 var drawPolygon = function (_a) {
   var ctx = _a.ctx,
@@ -80,19 +114,26 @@ var drawPolygon = function (_a) {
   }
 };
 /**
- * 폴리곤 Base 렌더링 함수
+ * 폴리곤 Base Layer 렌더링 함수 팩토리
  *
- * @param baseFillColor 기본 폴리곤 채우기 색상
- * @param baseStrokeColor 기본 폴리곤 테두리 색상
- * @param baseLineWidth 기본 폴리곤 테두리 두께
+ * 기본 상태의 폴리곤들을 렌더링하는 함수를 생성합니다.
+ * 선택된 폴리곤들은 Event Layer에서 렌더링되므로 제외됩니다.
+ *
+ * @param baseFillColor - 기본 폴리곤 채우기 색상
+ * @param baseStrokeColor - 기본 폴리곤 테두리 색상
+ * @param baseLineWidth - 기본 폴리곤 테두리 두께
  * @returns Base Layer 렌더링 함수
  *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ *
  * @example
+ * ```typescript
  * const renderBase = renderPolygonBase(
- *   'rgba(255, 100, 100, 0.5)',
- *   'rgba(200, 50, 50, 0.8)',
- *   2
+ *   'rgba(255, 100, 100, 0.5)',  // 기본 채우기 색상
+ *   'rgba(200, 50, 50, 0.8)',    // 기본 테두리 색상
+ *   2                             // 기본 테두리 두께
  * );
+ * ```
  */
 
 var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth) {
@@ -121,23 +162,35 @@ var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth)
   };
 };
 /**
- * 폴리곤 Event 렌더링 함수
+ * 폴리곤 Event Layer 렌더링 함수 팩토리
+ *
+ * 선택, 호버, 활성 상태의 폴리곤들을 렌더링하는 함수를 생성합니다.
+ * 다양한 상태에 따른 색상과 스타일을 지원하며, fallback 메커니즘을 제공합니다.
  *
- * @param baseFillColor 기본 폴리곤 채우기 색상 (필수, fallback용)
- * @param baseStrokeColor 기본 폴리곤 테두리 색상 (필수, fallback용)
- * @param baseLineWidth 기본 폴리곤 테두리 두께 (필수, fallback용)
- * @param selectedFillColor 선택된 폴리곤 채우기 색상 (선택, 기본값: baseFillColor)
- * @param selectedStrokeColor 선택된 폴리곤 테두리 색상 (선택, 기본값: baseStrokeColor)
- * @param selectedLineWidth 선택된 폴리곤 테두리 두께 (선택, 기본값: baseLineWidth)
- * @param activeFillColor 마지막 선택된 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
- * @param activeStrokeColor 마지막 선택된 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
- * @param activeLineWidth 마지막 선택된 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
- * @param hoveredFillColor Hover 시 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
- * @param hoveredStrokeColor Hover 시 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
- * @param hoveredLineWidth Hover 시 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+ * ## 상태별 렌더링 우선순위
+ * 1. **Hovered**: 마우스가 올라간 폴리곤 (최우선)
+ * 2. **Active**: 마지막으로 선택된 폴리곤
+ * 3. **Selected**: 선택된 폴리곤들
+ * 4. **Base**: 기본 상태 (fallback)
+ *
+ * @param baseFillColor - 기본 폴리곤 채우기 색상 (필수, fallback용)
+ * @param baseStrokeColor - 기본 폴리곤 테두리 색상 (필수, fallback용)
+ * @param baseLineWidth - 기본 폴리곤 테두리 두께 (필수, fallback용)
+ * @param selectedFillColor - 선택된 폴리곤 채우기 색상 (선택, 기본값: baseFillColor)
+ * @param selectedStrokeColor - 선택된 폴리곤 테두리 색상 (선택, 기본값: baseStrokeColor)
+ * @param selectedLineWidth - 선택된 폴리곤 테두리 두께 (선택, 기본값: baseLineWidth)
+ * @param activeFillColor - 마지막 선택된 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+ * @param activeStrokeColor - 마지막 선택된 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+ * @param activeLineWidth - 마지막 선택된 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+ * @param hoveredFillColor - Hover 시 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+ * @param hoveredStrokeColor - Hover 시 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+ * @param hoveredLineWidth - Hover 시 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
  * @returns Event Layer 렌더링 함수
  *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ *
  * @example
+ * ```typescript
  * const renderEvent = renderPolygonEvent(
  *   'rgba(255, 100, 100, 0.5)',  // baseFillColor
  *   'rgba(200, 50, 50, 0.8)',    // baseStrokeColor
@@ -146,6 +199,7 @@ var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth)
  *   'rgba(255, 152, 0, 1)',      // selectedStrokeColor
  *   4                             // selectedLineWidth
  * );
+ * ```
  */
 
 var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth, selectedFillColor, selectedStrokeColor, selectedLineWidth, activeFillColor, activeStrokeColor, activeLineWidth, hoveredFillColor, hoveredStrokeColor, hoveredLineWidth) {

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

@@ -1,49 +1,171 @@
+/**
+ * @fileoverview WoongCanvasLayer를 위한 유틸리티 함수들
+ *
+ * 이 파일은 좌표 변환, 히트 테스트, 색상 변환 등 WoongCanvasLayer에서
+ * 사용하는 다양한 유틸리티 함수들을 제공합니다.
+ *
+ * ## 주요 기능
+ * - **좌표 변환**: 지도 좌표(위경도) ↔ 화면 좌표(픽셀) 변환
+ * - **히트 테스트**: 마우스 클릭/호버 시 어떤 마커/폴리곤인지 찾기
+ * - **색상 변환**: 다양한 색상 형식 간 변환
+ * - **바운딩 박스**: 폴리곤의 경계 영역 계산
+ *
+ * @version 2.2.1
+ * @since 2.0.0
+ * @author 박건웅
+ */
 import { Offset } from "../../../../types";
 import { MintMapController } from "../../../MintMapController";
 import { KonvaCanvasData } from "./types";
 /**
- * 폴리곤 offset 계산
+ * 폴리곤 좌표를 화면 좌표로 변환
+ *
+ * GeoJSON MultiPolygon 형식의 폴리곤 데이터를 Canvas에서 그릴 수 있는
+ * 화면 좌표 배열로 변환합니다.
+ *
+ * @param polygonData - 변환할 폴리곤 데이터
+ * @param controller - 지도 컨트롤러 (좌표 변환용)
+ * @returns 변환된 좌표 배열 또는 null (변환 실패 시)
+ *
+ * @example
+ * ```typescript
+ * const offsets = computePolygonOffsets(polygonData, controller);
+ * if (offsets) {
+ *   // offsets[0][0][0] = [x, y] - 첫 번째 MultiPolygon의 첫 번째 Polygon의 첫 번째 점
+ * }
+ * ```
  */
 export declare const computePolygonOffsets: (polygonData: KonvaCanvasData<any>, controller: MintMapController) => number[][][][] | null;
 /**
- * 마커 offset 계산
+ * 마커 좌표를 화면 좌표로 변환
+ *
+ * 마커의 지도 좌표(위경도)를 Canvas에서 그릴 수 있는 화면 좌표로 변환합니다.
+ *
+ * @param markerData - 변환할 마커 데이터
+ * @param controller - 지도 컨트롤러 (좌표 변환용)
+ * @returns 변환된 화면 좌표 또는 null (변환 실패 시)
+ *
+ * @example
+ * ```typescript
+ * const offset = computeMarkerOffset(markerData, controller);
+ * if (offset) {
+ *   console.log(`마커 위치: (${offset.x}, ${offset.y})`);
+ * }
+ * ```
  */
 export declare const computeMarkerOffset: (markerData: KonvaCanvasData<any>, controller: MintMapController) => Offset | null;
 /**
- * Point-in-Polygon 알고리즘
+ * Point-in-Polygon 알고리즘 (Ray Casting)
+ *
+ * 주어진 점이 폴리곤 내부에 있는지 확인하는 알고리즘입니다.
+ * Ray Casting 방식을 사용하여 홀수 번 교차하면 내부, 짝수 번 교차하면 외부로 판단합니다.
+ *
+ * @param point - 확인할 점의 좌표
+ * @param polygon - 폴리곤의 좌표 배열 (순서대로 연결된 점들)
+ * @returns 점이 폴리곤 내부에 있으면 true, 외부에 있으면 false
+ *
+ * @example
+ * ```typescript
+ * const point = { x: 100, y: 100 };
+ * const polygon = [[0, 0], [200, 0], [200, 200], [0, 200]];
+ * const isInside = isPointInPolygon(point, polygon); // true
+ * ```
  */
 export declare const isPointInPolygon: (point: Offset, polygon: number[][]) => boolean;
 /**
  * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
  *
- * 로직:
- * 1. 외부 폴리곤(첫 번째): 내부에 있어야 함
- * 2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
+ * 클릭된 좌표가 폴리곤 내부에 있는지 확인합니다.
+ * 도넛 폴리곤(구멍이 있는 폴리곤)도 지원합니다.
  *
- * 중요: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됨
- * - 도넛 폴리곤 A: isDonutPolygon=true
- * - 내부 폴리곤 B: isDonutPolygon=false (별도 데이터)
+ * ## 도넛 폴리곤 처리 로직
+ * 1. **외부 폴리곤(첫 번째)**: 내부에 있어야 함
+ * 2. **내부 구멍들(나머지)**: 내부에 있으면 안 됨 (evenodd 규칙)
+ *
+ * ## 중요 사항
+ * 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됩니다:
+ * - 도넛 폴리곤 A: `isDonutPolygon=true`
+ * - 내부 폴리곤 B: `isDonutPolygon=false` (별도 데이터)
+ *
+ * @param clickedOffset - 클릭된 좌표
+ * @param polygonData - 확인할 폴리곤 데이터
+ * @param getPolygonOffsets - 폴리곤 좌표를 가져오는 함수
+ * @returns 클릭된 좌표가 폴리곤 내부에 있으면 true, 외부에 있으면 false
+ *
+ * @example
+ * ```typescript
+ * const isHit = isPointInPolygonData(
+ *   { x: 100, y: 100 },
+ *   polygonData,
+ *   (data) => computePolygonOffsets(data, controller)
+ * );
+ * ```
  */
 export declare const isPointInPolygonData: (clickedOffset: Offset, polygonData: KonvaCanvasData<any>, getPolygonOffsets: (data: KonvaCanvasData<any>) => number[][][][] | null) => boolean;
 /**
  * 마커 히트 테스트 (클릭/hover 영역 체크)
  *
- * 🎯 중요: 꼬리(tail)는 Hit Test 영역에서 제외됩니다!
- * - markerOffset.y는 마커 최하단(꼬리 끝) 좌표
- * - boxHeight는 마커 본체만 포함 (꼬리 제외)
- * - tailHeight만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+ * 클릭된 좌표가 마커의 클릭 가능한 영역 내부에 있는지 확인합니다.
+ *
+ * ## 중요 사항
+ * **꼬리(tail)는 Hit Test 영역에서 제외됩니다!**
+ * - `markerOffset.y`는 마커 최하단(꼬리 끝) 좌표
+ * - `boxHeight`는 마커 본체만 포함 (꼬리 제외)
+ * - `tailHeight`만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+ *
+ * @param clickedOffset - 클릭된 좌표
+ * @param markerData - 확인할 마커 데이터
+ * @param getMarkerOffset - 마커 좌표를 가져오는 함수
+ * @returns 클릭된 좌표가 마커 내부에 있으면 true, 외부에 있으면 false
+ *
+ * @example
+ * ```typescript
+ * const isHit = isPointInMarkerData(
+ *   { x: 100, y: 100 },
+ *   markerData,
+ *   (data) => computeMarkerOffset(data, controller)
+ * );
+ * ```
  */
 export declare const isPointInMarkerData: (clickedOffset: Offset, markerData: KonvaCanvasData<any>, getMarkerOffset: (data: KonvaCanvasData<any>) => Offset | null) => boolean;
+/**
+ * HEX 색상을 RGBA 색상으로 변환
+ *
+ * 16진수 색상 코드를 RGBA 형식으로 변환합니다.
+ *
+ * @param hexColor - 변환할 HEX 색상 (예: "#FF0000" 또는 "FF0000")
+ * @param alpha - 알파 값 (0~1, 기본값: 1)
+ * @returns RGBA 형식의 색상 문자열
+ *
+ * @example
+ * ```typescript
+ * const rgba = hexToRgba('#FF0000', 0.5); // "rgba(255, 0, 0, 0.5)"
+ * const rgba2 = hexToRgba('FF0000', 1);   // "rgba(255, 0, 0, 1)"
+ * ```
+ */
 export declare const hexToRgba: (hexColor: string, alpha?: number) => string;
 /**
- * 텍스트 박스의 너비를 계산합니다.
+ * 텍스트 박스의 너비를 계산
+ *
+ * Canvas 2D API의 measureText()를 사용하여 텍스트의 실제 너비를 측정하고,
+ * 패딩과 최소 너비를 고려하여 최종 박스 너비를 계산합니다.
+ *
+ * @param params - 파라미터 객체
+ * @param params.text - 측정할 텍스트
+ * @param params.fontConfig - 폰트 설정 (예: 'bold 16px Arial')
+ * @param params.padding - 텍스트 박스에 적용할 패딩 값
+ * @param params.minWidth - 최소 너비
+ * @returns 계산된 텍스트 박스의 너비
  *
- * @param {Object} params - 파라미터 객체
- * @param {string} params.text - 측정할 텍스트
- * @param {string} params.fontConfig - 폰트 설정 (예: 'bold 16px Arial')
- * @param {number} params.padding - 텍스트 박스에 적용할 패딩 값
- * @param {number} params.minWidth - 최소 너비
- * @returns {number} 계산된 텍스트 박스의 너비
+ * @example
+ * ```typescript
+ * const width = calculateTextBoxWidth({
+ *   text: 'Hello World',
+ *   fontConfig: 'bold 16px Arial',
+ *   padding: 10,
+ *   minWidth: 50
+ * });
+ * ```
  */
 export declare const calculateTextBoxWidth: ({ text, fontConfig, padding, minWidth, }: {
     text: string;