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

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

@@ -7,7 +7,38 @@ var MapTypes = require('../../../../types/MapTypes.js');
 require('../../../../types/MapEventTypes.js');
 
 /**
- * 폴리곤 offset 계산
+ * @fileoverview WoongCanvasLayer를 위한 유틸리티 함수들
+ *
+ * 이 파일은 좌표 변환, 히트 테스트, 색상 변환 등 WoongCanvasLayer에서
+ * 사용하는 다양한 유틸리티 함수들을 제공합니다.
+ *
+ * ## 주요 기능
+ * - **좌표 변환**: 지도 좌표(위경도) ↔ 화면 좌표(픽셀) 변환
+ * - **히트 테스트**: 마우스 클릭/호버 시 어떤 마커/폴리곤인지 찾기
+ * - **색상 변환**: 다양한 색상 형식 간 변환
+ * - **바운딩 박스**: 폴리곤의 경계 영역 계산
+ *
+ * @version 2.2.1
+ * @since 2.0.0
+ * @author 박건웅
+ */
+/**
+ * 폴리곤 좌표를 화면 좌표로 변환
+ *
+ * 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의 첫 번째 점
+ * }
+ * ```
  */
 
 var computePolygonOffsets = function (polygonData, controller) {
@@ -43,7 +74,21 @@ var computePolygonOffsets = function (polygonData, controller) {
   return result;
 };
 /**
- * 마커 offset 계산
+ * 마커 좌표를 화면 좌표로 변환
+ *
+ * 마커의 지도 좌표(위경도)를 Canvas에서 그릴 수 있는 화면 좌표로 변환합니다.
+ *
+ * @param markerData - 변환할 마커 데이터
+ * @param controller - 지도 컨트롤러 (좌표 변환용)
+ * @returns 변환된 화면 좌표 또는 null (변환 실패 시)
+ *
+ * @example
+ * ```typescript
+ * const offset = computeMarkerOffset(markerData, controller);
+ * if (offset) {
+ *   console.log(`마커 위치: (${offset.x}, ${offset.y})`);
+ * }
+ * ```
  */
 
 var computeMarkerOffset = function (markerData, controller) {
@@ -54,7 +99,21 @@ var computeMarkerOffset = function (markerData, controller) {
   return controller.positionToOffset(markerData.position);
 };
 /**
- * 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
+ * ```
  */
 
 var isPointInPolygon = function (point, polygon) {
@@ -74,13 +133,31 @@ var isPointInPolygon = function (point, polygon) {
 /**
  * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
  *
- * 로직:
- * 1. 외부 폴리곤(첫 번째): 내부에 있어야 함
- * 2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
+ * 클릭된 좌표가 폴리곤 내부에 있는지 확인합니다.
+ * 도넛 폴리곤(구멍이 있는 폴리곤)도 지원합니다.
+ *
+ * ## 도넛 폴리곤 처리 로직
+ * 1. **외부 폴리곤(첫 번째)**: 내부에 있어야 함
+ * 2. **내부 구멍들(나머지)**: 내부에 있으면 안 됨 (evenodd 규칙)
  *
- * 중요: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됨
- * - 도넛 폴리곤 A: isDonutPolygon=true
- * - 내부 폴리곤 B: isDonutPolygon=false (별도 데이터)
+ * ## 중요 사항
+ * 도넛 폴리곤과 내부 폴리곤은 별개의 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)
+ * );
+ * ```
  */
 
 var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffsets) {
@@ -145,10 +222,27 @@ var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffse
 /**
  * 마커 히트 테스트 (클릭/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)
+ * );
+ * ```
  */
 
 var isPointInMarkerData = function (clickedOffset, markerData, getMarkerOffset) {
@@ -163,13 +257,29 @@ var isPointInMarkerData = function (clickedOffset, markerData, getMarkerOffset)
 
   return clickedOffset.x >= x && clickedOffset.x <= x + boxWidth && clickedOffset.y >= y && clickedOffset.y <= y + boxHeight;
 };
+/**
+ * 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)"
+ * ```
+ */
+
 var hexToRgba = function (hexColor, alpha) {
   if (alpha === void 0) {
     alpha = 1;
-  } // NOTE: 입력된 hexColor에서 "#" 제거
+  } // 입력된 hexColor에서 "#" 제거
 
 
-  var hex = hexColor.replace('#', ''); // NOTE: 6자리일 경우 알파 값은 사용자가 제공한 alpha 값으로 설정
+  var hex = hexColor.replace('#', ''); // 6자리일 경우 알파 값은 사용자가 제공한 alpha 값으로 설정
 
   if (hex.length === 6) {
     var r = parseInt(hex.substring(0, 2), 16);
@@ -183,14 +293,27 @@ var hexToRgba = function (hexColor, alpha) {
 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} 계산된 텍스트 박스의 너비
+ * 텍스트 박스의 너비를 계산
+ *
+ * Canvas 2D API의 measureText()를 사용하여 텍스트의 실제 너비를 측정하고,
+ * 패딩과 최소 너비를 고려하여 최종 박스 너비를 계산합니다.
+ *
+ * @param params - 파라미터 객체
+ * @param params.text - 측정할 텍스트
+ * @param params.fontConfig - 폰트 설정 (예: 'bold 16px Arial')
+ * @param params.padding - 텍스트 박스에 적용할 패딩 값
+ * @param params.minWidth - 최소 너비
+ * @returns 계산된 텍스트 박스의 너비
+ *
+ * @example
+ * ```typescript
+ * const width = calculateTextBoxWidth({
+ *   text: 'Hello World',
+ *   fontConfig: 'bold 16px Arial',
+ *   padding: 10,
+ *   minWidth: 50
+ * });
+ * ```
  */
 
 var calculateTextBoxWidth = function (_a) {