@mint-ui/map 1.2.0-test.34 → 1.2.0-test.36

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

@@ -2,24 +2,22 @@ import Konva from "konva";
 import { Position, Offset } from "../../../types";
 /**
  * 캔버스 데이터 타입 Enum
- * 마커인지 폴리곤인지 구분하는 상수
  */
 export declare enum CanvasDataType {
     MARKER = "MARKER",
     POLYGON = "POLYGON"
 }
 /**
- * 폴리곤 경로 정의
+ * 폴리곤 경로 정의 (GeoJSON MultiPolygon 형식)
  */
 export interface Paths {
     type: string;
     coordinates: number[][][][];
 }
 /**
- * Konva 캔버스 마커/폴리곤의 기본 필수 속성
- * (렌더링에 필요한 최소 정보)
+ * 캔버스 마커/폴리곤의 기본 필수 속성
  */
-export interface KonvaCanvasOption {
+export interface CanvasOption {
     id: string;
     position: Position;
     boxWidth?: number;
@@ -30,196 +28,63 @@ export interface KonvaCanvasOption {
 }
 /**
  * 서버 데이터와 캔버스 옵션을 결합한 타입
- * @template T 서버에서 받은 원본 데이터 타입 (예: Marker, Polygon)
- * @example
- * // API에서 받은 Marker 타입을 그대로 유지하면서 캔버스 렌더링 정보 추가
- * type MarkerWithCanvas = KonvaCanvasData<Marker>
- * // { raId, lat, lng, buildingName, totalArea } + { id, position, boxWidth, ... }
+ *
+ * @template T 서버에서 받은 원본 데이터 타입
  */
-export declare type KonvaCanvasData<T = {}> = T & KonvaCanvasOption;
+export declare type CanvasData<T = {}> = T & CanvasOption;
 /**
- * 🛠️ 렌더링 유틸리티 함수들
- *
- * WoongCanvasMarker/WoongCanvasPolygon이 제공하는 헬퍼 함수 모음입니다.
- * 커스텀 렌더링 함수 내에서 좌표 변환 시 사용하세요.
- *
- * ## 주요 기능
- * - **자동 캐싱**: 좌표 변환 결과를 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: KonvaCanvasData<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: KonvaCanvasData<T>) => Offset | null;
+    getOrComputePolygonOffsets: (polygonData: CanvasData<T>) => number[][][][] | null;
+    getOrComputeMarkerOffset: (markerData: CanvasData<T>) => Offset | null;
 }
 /**
  * 커스텀 렌더링 함수 파라미터 - Base Layer
  */
 export interface RenderBaseParams<T> {
-    /** Canvas 2D 렌더링 컨텍스트 (순수 Canvas API) */
     ctx: CanvasRenderingContext2D;
-    /** 렌더링할 마커/폴리곤 데이터 배열 */
-    items: KonvaCanvasData<T>[];
-    /** 현재 선택된 마커/폴리곤 ID Set */
+    items: CanvasData<T>[];
     selectedIds: Set<string>;
-    /** 현재 hover된 마커/폴리곤 데이터 (선택) */
-    hoveredItem?: KonvaCanvasData<T> | null;
-    /** 렌더링 유틸리티 함수들 */
+    hoveredItem?: CanvasData<T> | null;
     utils: RenderUtils<T>;
 }
 /**
  * 커스텀 렌더링 함수 타입 - Base Layer
  *
- * 🔥 순수 Canvas API 사용 (Konva 지식 불필요!)
- *
- * @example
- * const renderBase = ({ ctx, items, selectedIds, utils }) => {
- *   for (const item of items) {
- *     if (selectedIds.has(item.id)) continue;
- *     const pos = utils.getOrComputeMarkerOffset(item);
- *     ctx.fillRect(pos.x, pos.y, 50, 50); // 순수 Canvas API!
- *   }
- * };
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
  */
 export declare type CustomRenderBase<T> = (params: RenderBaseParams<T>) => void;
 /**
  * 커스텀 렌더링 함수 파라미터 - Animation Layer
  */
 export interface RenderAnimationParams<T> {
-    /** Konva Layer 인스턴스 */
     layer: Konva.Layer;
-    /** 현재 선택된 마커/폴리곤 ID Set */
     selectedIds: Set<string>;
-    /** 전체 마커/폴리곤 데이터 배열 */
-    items: KonvaCanvasData<T>[];
-    /** 렌더링 유틸리티 함수들 */
+    items: CanvasData<T>[];
     utils: RenderUtils<T>;
 }
 /**
  * 커스텀 렌더링 함수 타입 - Animation Layer (선택)
  *
- * @example
- * const renderAnimation = ({ layer, selectedIds, items, utils }) => {
- *   for (const id of selectedIds) {
- *     const item = items.find(i => i.id === id);
- *     // Konva 애니메이션 구현
- *   }
- * };
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
  */
 export declare type CustomRenderAnimation<T> = (params: RenderAnimationParams<T>) => void;
 /**
  * 커스텀 렌더링 함수 파라미터 - Event Layer
  */
 export interface RenderEventParams<T> {
-    /** Canvas 2D 렌더링 컨텍스트 (순수 Canvas API) */
     ctx: CanvasRenderingContext2D;
-    /** 현재 hover된 마커/폴리곤 데이터 */
-    hoveredItem: KonvaCanvasData<T> | null;
-    /** 렌더링 유틸리티 함수들 */
+    hoveredItem: CanvasData<T> | null;
     utils: RenderUtils<T>;
-    /** 현재 선택된 마커/폴리곤 데이터 배열 (선택 강조용) */
-    selectedItems?: KonvaCanvasData<T>[];
-    /** 외부에서 전달된 단일 선택 아이템 (특별한 효과용) */
-    selectedItem?: KonvaCanvasData<T> | null;
+    selectedItems?: CanvasData<T>[];
+    selectedItem?: CanvasData<T> | null;
 }
 /**
  * 커스텀 렌더링 함수 타입 - Event Layer
  *
- * 🔥 순수 Canvas API 사용 (Konva 지식 불필요!)
- *
- * @example
- * const renderEvent = ({ ctx, hoveredItem, utils, selectedItems }) => {
- *   if (hoveredItem) {
- *     const pos = utils.getOrComputeMarkerOffset(hoveredItem);
- *     ctx.fillStyle = 'red';
- *     ctx.fillRect(pos.x, pos.y, 50, 50); // 순수 Canvas API!
- *   }
- * };
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
  */
 export declare type CustomRenderEvent<T> = (params: RenderEventParams<T>) => void;

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

@@ -4,7 +4,6 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 /**
  * 캔버스 데이터 타입 Enum
- * 마커인지 폴리곤인지 구분하는 상수
  */
 exports.CanvasDataType = void 0;
 

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

@@ -1,49 +1,58 @@
 import { Offset } from "../../../types";
 import { MintMapController } from "../../MintMapController";
-import { KonvaCanvasData } from "./types";
+import { CanvasData } from "./types";
 /**
- * 폴리곤 offset 계산
+ * 폴리곤 좌표 변환 (위경도 → 화면 좌표)
+ *
+ * @param polygonData 폴리곤 데이터
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 배열 (4차원 배열) 또는 null
  */
-export declare const computePolygonOffsets: (polygonData: KonvaCanvasData<any>, controller: MintMapController) => number[][][][] | null;
+export declare const computePolygonOffsets: (polygonData: CanvasData<any>, controller: MintMapController) => number[][][][] | null;
 /**
- * 마커 offset 계산
+ * 마커 좌표 변환 (위경도 → 화면 좌표)
+ *
+ * @param markerData 마커 데이터
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 또는 null
  */
-export declare const computeMarkerOffset: (markerData: KonvaCanvasData<any>, controller: MintMapController) => Offset | null;
+export declare const computeMarkerOffset: (markerData: CanvasData<any>, controller: MintMapController) => Offset | null;
 /**
- * Point-in-Polygon 알고리즘
+ * Point-in-Polygon 알고리즘 (Ray Casting)
+ *
+ * @param point 확인할 점의 좌표
+ * @param polygon 폴리곤 좌표 배열
+ * @returns 점이 폴리곤 내부에 있으면 true
  */
 export declare const isPointInPolygon: (point: Offset, polygon: number[][]) => boolean;
 /**
  * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
  *
- * 로직:
- * 1. 외부 폴리곤(첫 번째): 내부에 있어야 함
- * 2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
- *
- * 중요: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됨
- * - 도넛 폴리곤 A: isDonutPolygon=true
- * - 내부 폴리곤 B: isDonutPolygon=false (별도 데이터)
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param polygonData 폴리곤 데이터
+ * @param getPolygonOffsets 폴리곤 좌표 변환 함수
+ * @returns 점이 폴리곤 내부에 있으면 true
  */
-export declare const isPointInPolygonData: (clickedOffset: Offset, polygonData: KonvaCanvasData<any>, getPolygonOffsets: (data: KonvaCanvasData<any>) => number[][][][] | null) => boolean;
+export declare const isPointInPolygonData: (clickedOffset: Offset, polygonData: CanvasData<any>, getPolygonOffsets: (data: CanvasData<any>) => number[][][][] | null) => boolean;
 /**
- * 마커 히트 테스트 (클릭/hover 영역 체크)
+ * 마커 히트 테스트 (꼬리 제외)
  *
- * 🎯 중요: 꼬리(tail)는 Hit Test 영역에서 제외됩니다!
- * - markerOffset.y는 마커 최하단(꼬리 끝) 좌표
- * - boxHeight는 마커 본체만 포함 (꼬리 제외)
- * - tailHeight만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param markerData 마커 데이터
+ * @param getMarkerOffset 마커 좌표 변환 함수
+ * @returns 점이 마커 영역 내부에 있으면 true
  */
-export declare const isPointInMarkerData: (clickedOffset: Offset, markerData: KonvaCanvasData<any>, getMarkerOffset: (data: KonvaCanvasData<any>) => Offset | null) => boolean;
+export declare const isPointInMarkerData: (clickedOffset: Offset, markerData: CanvasData<any>, getMarkerOffset: (data: CanvasData<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} 계산된 텍스트 박스의 너비
+ * @param params 파라미터 객체
+ * @param params.text 측정할 텍스트
+ * @param params.fontConfig 폰트 설정
+ * @param params.padding 패딩 값 (px)
+ * @param params.minWidth 최소 너비 (px)
+ * @returns 계산된 텍스트 박스 너비 (px)
  */
 export declare const calculateTextBoxWidth: ({ text, fontConfig, padding, minWidth, }: {
     text: string;

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

@@ -7,7 +7,11 @@ var MapTypes = require('../../../types/MapTypes.js');
 require('../../../types/MapEventTypes.js');
 
 /**
- * 폴리곤 offset 계산
+ * 폴리곤 좌표 변환 (위경도 → 화면 좌표)
+ *
+ * @param polygonData 폴리곤 데이터
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 배열 (4차원 배열) 또는 null
  */
 
 var computePolygonOffsets = function (polygonData, controller) {
@@ -17,7 +21,7 @@ var computePolygonOffsets = function (polygonData, controller) {
     return null;
   }
 
-  var result = [];
+  var result = []; // GeoJSON MultiPolygon 구조: [MultiPolygon][PolygonGroup][Coordinate][lng, lat]
 
   for (var _i = 0, _a = paths.coordinates; _i < _a.length; _i++) {
     var multiPolygon = _a[_i];
@@ -28,7 +32,8 @@ var computePolygonOffsets = function (polygonData, controller) {
       var polygonOffsets = [];
 
       for (var _c = 0, polygonGroup_1 = polygonGroup; _c < polygonGroup_1.length; _c++) {
-        var coord = polygonGroup_1[_c];
+        var coord = polygonGroup_1[_c]; // GeoJSON은 [lng, lat] 순서이지만 Position은 [lat, lng] 순서
+
         var pos = new MapTypes.Position(coord[1], coord[0]);
         var offset = controller.positionToOffset(pos);
         polygonOffsets.push([offset.x, offset.y]);
@@ -43,30 +48,37 @@ var computePolygonOffsets = function (polygonData, controller) {
   return result;
 };
 /**
- * 마커 offset 계산
+ * 마커 좌표 변환 (위경도 → 화면 좌표)
+ *
+ * @param markerData 마커 데이터
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 또는 null
  */
 
 var computeMarkerOffset = function (markerData, controller) {
-  if (!markerData.position) {
-    return null;
-  }
-
+  if (!markerData.position) return null;
   return controller.positionToOffset(markerData.position);
 };
 /**
- * Point-in-Polygon 알고리즘
+ * Point-in-Polygon 알고리즘 (Ray Casting)
+ *
+ * @param point 확인할 점의 좌표
+ * @param polygon 폴리곤 좌표 배열
+ * @returns 점이 폴리곤 내부에 있으면 true
  */
 
 var isPointInPolygon = function (point, polygon) {
+  // Ray Casting 알고리즘: 점에서 오른쪽으로 무한히 뻗은 선과 폴리곤 변의 교차 횟수로 판단
   var inside = false;
 
   for (var i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
     var xi = polygon[i][0],
         yi = polygon[i][1];
     var xj = polygon[j][0],
-        yj = polygon[j][1];
+        yj = polygon[j][1]; // 점의 y 좌표가 변의 양 끝점 사이에 있고, 교차점의 x 좌표가 점의 x 좌표보다 큰지 확인
+
     var intersect = yi > point.y !== yj > point.y && point.x < (xj - xi) * (point.y - yi) / (yj - yi) + xi;
-    if (intersect) inside = !inside;
+    if (intersect) inside = !inside; // 교차할 때마다 inside 상태 토글
   }
 
   return inside;
@@ -74,23 +86,20 @@ var isPointInPolygon = function (point, polygon) {
 /**
  * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
  *
- * 로직:
- * 1. 외부 폴리곤(첫 번째): 내부에 있어야 함
- * 2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
- *
- * 중요: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됨
- * - 도넛 폴리곤 A: isDonutPolygon=true
- * - 내부 폴리곤 B: isDonutPolygon=false (별도 데이터)
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param polygonData 폴리곤 데이터
+ * @param getPolygonOffsets 폴리곤 좌표 변환 함수
+ * @returns 점이 폴리곤 내부에 있으면 true
  */
 
 var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffsets) {
   var polygonOffsets = getPolygonOffsets(polygonData);
-  if (!polygonOffsets) return false; // 🍩 도넛 폴리곤 처리 (isDonutPolygon === true)
+  if (!polygonOffsets) return false; // 도넛 폴리곤 처리: 외부 폴리곤 내부에 있으면서 구멍(hole) 내부에 있지 않아야 함
 
   if (polygonData.isDonutPolygon) {
     for (var _i = 0, polygonOffsets_1 = polygonOffsets; _i < polygonOffsets_1.length; _i++) {
       var multiPolygon = polygonOffsets_1[_i];
-      if (multiPolygon.length === 0) continue; // 외부 폴리곤만 있는 경우 (구멍 없음) - 일반 폴리곤처럼 처리
+      if (multiPolygon.length === 0) continue; // 구멍이 없는 경우 일반 폴리곤과 동일
 
       if (multiPolygon.length === 1) {
         if (isPointInPolygon(clickedOffset, multiPolygon[0])) {
@@ -98,33 +107,30 @@ var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffse
         }
 
         continue;
-      } // 1. 외부 폴리곤(첫 번째)에 포함되는지 확인
+      } // 외부 폴리곤 내부에 있는지 확인
 
 
       var outerPolygon = multiPolygon[0];
 
       if (!isPointInPolygon(clickedOffset, outerPolygon)) {
-        continue; // 외부 폴리곤 밖이면 다음 multiPolygon 확인
-      } // 2. 내부 구멍들(나머지)에 포함되는지 확인
+        continue;
+      } // 구멍 내부에 있으면 false (도넛의 빈 공간)
 
 
       for (var i = 1; i < multiPolygon.length; i++) {
         var hole = multiPolygon[i];
 
         if (isPointInPolygon(clickedOffset, hole)) {
-          // ❌ 구멍 안에 있음 → 이 도넛 폴리곤은 히트 안 됨
-          // 다른 multiPolygon 체크하지 않고 바로 false 반환
-          // (도넛 폴리곤의 구멍 안은 무조건 클릭 불가)
           return false;
         }
-      } // ✅ 외부 폴리곤 안 + 구멍 밖 = 히트!
+      } // 외부 폴리곤 내부에 있으면서 모든 구멍 밖에 있으면 true
 
 
       return true;
     }
 
     return false;
-  } // 일반 폴리곤 처리 (isDonutPolygon === false 또는 undefined)
+  } // 일반 폴리곤 처리
 
 
   for (var _a = 0, polygonOffsets_2 = polygonOffsets; _a < polygonOffsets_2.length; _a++) {
@@ -143,12 +149,12 @@ var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffse
   return false;
 };
 /**
- * 마커 히트 테스트 (클릭/hover 영역 체크)
+ * 마커 히트 테스트 (꼬리 제외)
  *
- * 🎯 중요: 꼬리(tail)는 Hit Test 영역에서 제외됩니다!
- * - markerOffset.y는 마커 최하단(꼬리 끝) 좌표
- * - boxHeight는 마커 본체만 포함 (꼬리 제외)
- * - tailHeight만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param markerData 마커 데이터
+ * @param getMarkerOffset 마커 좌표 변환 함수
+ * @returns 점이 마커 영역 내부에 있으면 true
  */
 
 var isPointInMarkerData = function (clickedOffset, markerData, getMarkerOffset) {
@@ -156,41 +162,41 @@ var isPointInMarkerData = function (clickedOffset, markerData, getMarkerOffset)
   if (!markerOffset) return false;
   var boxWidth = markerData.boxWidth || 50;
   var boxHeight = markerData.boxHeight || 28;
-  var tailHeight = markerData.tailHeight || 0; // 🎯 tailHeight 사용!
+  var tailHeight = markerData.tailHeight || 0; // 마커 중심점 기준으로 박스 영역 계산 (꼬리는 제외)
 
   var x = markerOffset.x - boxWidth / 2;
-  var y = markerOffset.y - boxHeight - tailHeight; // 🔥 꼬리만큼 위로!
+  var y = markerOffset.y - boxHeight - tailHeight; // 클릭 위치가 박스 영역 내부에 있는지 확인
 
   return clickedOffset.x >= x && clickedOffset.x <= x + boxWidth && clickedOffset.y >= y && clickedOffset.y <= y + boxHeight;
-};
+}; // Hex 색상을 RGBA로 변환
+
 var hexToRgba = function (hexColor, alpha) {
   if (alpha === void 0) {
     alpha = 1;
-  } // NOTE: 입력된 hexColor에서 "#" 제거
-
+  }
 
-  var hex = hexColor.replace('#', ''); // NOTE: 6자리일 경우 알파 값은 사용자가 제공한 alpha 값으로 설정
+  var hex = hexColor.replace('#', '');
 
-  if (hex.length === 6) {
-    var r = parseInt(hex.substring(0, 2), 16);
-    var g = parseInt(hex.substring(2, 4), 16);
-    var b = parseInt(hex.substring(4, 6), 16);
-    return "rgba(".concat(r, ", ").concat(g, ", ").concat(b, ", ").concat(alpha, ")");
+  if (hex.length !== 6) {
+    throw new Error('Invalid hex color format');
   }
 
-  throw new Error('Invalid hex color format');
+  var r = parseInt(hex.substring(0, 2), 16);
+  var g = parseInt(hex.substring(2, 4), 16);
+  var b = parseInt(hex.substring(4, 6), 16);
+  return "rgba(".concat(r, ", ").concat(g, ", ").concat(b, ", ").concat(alpha, ")");
 };
 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} 계산된 텍스트 박스의 너비
+ * @param params 파라미터 객체
+ * @param params.text 측정할 텍스트
+ * @param params.fontConfig 폰트 설정
+ * @param params.padding 패딩 값 (px)
+ * @param params.minWidth 최소 너비 (px)
+ * @returns 계산된 텍스트 박스 너비 (px)
  */
 
 var calculateTextBoxWidth = function (_a) {

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

@@ -0,0 +1,42 @@
+import { MutableRefObject } from "react";
+import { CanvasData } from "./types";
+/**
+ * 뷰포트 영역 (화면에 보이는 영역)
+ */
+export interface ViewportBounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+/**
+ * 바운딩 박스 (마커/폴리곤의 최소/최대 좌표)
+ */
+export interface BoundingBox {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/**
+ * 현재 뷰포트 영역 계산
+ *
+ * @param stage Konva Stage 인스턴스
+ * @param cullingMargin 컬링 여유 공간 (px)
+ * @param viewportRef 뷰포트 경계를 저장할 ref
+ */
+export declare const updateViewport: (stage: {
+    width: () => number;
+    height: () => number;
+} | null, cullingMargin: number, viewportRef: MutableRefObject<ViewportBounds | null>) => void;
+/**
+ * 아이템이 현재 뷰포트 안에 있는지 확인 (바운딩 박스 캐싱)
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param item 확인할 아이템
+ * @param viewportRef 뷰포트 경계 ref
+ * @param boundingBoxCacheRef 바운딩 박스 캐시 ref
+ * @param computeBoundingBox 바운딩 박스 계산 함수
+ * @returns 뷰포트 안에 있으면 true
+ */
+export declare const isInViewport: <T>(item: CanvasData<T>, viewportRef: MutableRefObject<ViewportBounds | null>, boundingBoxCacheRef: MutableRefObject<Map<string, BoundingBox>>, computeBoundingBox: (item: CanvasData<T>) => BoundingBox | null) => boolean;

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

@@ -0,0 +1,51 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * 현재 뷰포트 영역 계산
+ *
+ * @param stage Konva Stage 인스턴스
+ * @param cullingMargin 컬링 여유 공간 (px)
+ * @param viewportRef 뷰포트 경계를 저장할 ref
+ */
+var updateViewport = function (stage, cullingMargin, viewportRef) {
+  if (!stage) return;
+  viewportRef.current = {
+    minX: -cullingMargin,
+    maxX: stage.width() + cullingMargin,
+    minY: -cullingMargin,
+    maxY: stage.height() + cullingMargin
+  };
+};
+/**
+ * 아이템이 현재 뷰포트 안에 있는지 확인 (바운딩 박스 캐싱)
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param item 확인할 아이템
+ * @param viewportRef 뷰포트 경계 ref
+ * @param boundingBoxCacheRef 바운딩 박스 캐시 ref
+ * @param computeBoundingBox 바운딩 박스 계산 함수
+ * @returns 뷰포트 안에 있으면 true
+ */
+
+var isInViewport = function (item, viewportRef, boundingBoxCacheRef, computeBoundingBox) {
+  if (!viewportRef.current) return true;
+  var viewport = viewportRef.current; // 캐시된 바운딩 박스 확인
+
+  var bbox = boundingBoxCacheRef.current.get(item.id);
+
+  if (!bbox) {
+    // 바운딩 박스 계산 (공통 함수 사용)
+    var computed = computeBoundingBox(item);
+    if (!computed) return false;
+    bbox = computed;
+    boundingBoxCacheRef.current.set(item.id, bbox);
+  } // 바운딩 박스와 viewport 교차 체크
+
+
+  return !(bbox.maxX < viewport.minX || bbox.minX > viewport.maxX || bbox.maxY < viewport.minY || bbox.minY > viewport.maxY);
+};
+
+exports.isInViewport = isInViewport;
+exports.updateViewport = updateViewport;