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

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

@@ -3,47 +3,161 @@ import { MintMapController } from "../../MintMapController";
 import { KonvaCanvasData } from "./types";
 /**
  * 폴리곤 offset 계산
+ *
+ * GeoJSON MultiPolygon 형식의 위경도 좌표를 화면 픽셀 좌표로 변환합니다.
+ *
+ * @param polygonData 폴리곤 데이터 (paths 필드 필수)
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 배열 (4차원 배열) 또는 null (변환 실패 시)
+ *
+ * @remarks
+ * - 반환 형식: [MultiPolygon][Polygon][Point][x/y]
+ * - 성능: O(n), n은 폴리곤의 총 좌표 수
+ * - GeoJSON MultiPolygon 형식 지원
+ *
+ * @example
+ * ```typescript
+ * const offsets = computePolygonOffsets(polygonData, controller);
+ * if (!offsets) return; // 변환 실패
+ *
+ * // offsets 구조: [MultiPolygon][Polygon][Point][x/y]
+ * for (const multiPolygon of offsets) {
+ *   for (const polygon of multiPolygon) {
+ *     // polygon은 [Point][x/y] 배열
+ *   }
+ * }
+ * ```
  */
 export declare const computePolygonOffsets: (polygonData: KonvaCanvasData<any>, controller: MintMapController) => number[][][][] | null;
 /**
  * 마커 offset 계산
+ *
+ * 마커의 위경도 좌표를 화면 픽셀 좌표로 변환합니다.
+ *
+ * @param markerData 마커 데이터 (position 필드 필수)
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 (Offset) 또는 null (변환 실패 시)
+ *
+ * @remarks
+ * - 반환된 좌표는 마커의 중심점 (x, y)
+ * - 성능: O(1) - 단일 좌표 변환
+ *
+ * @example
+ * ```typescript
+ * const offset = computeMarkerOffset(markerData, controller);
+ * if (!offset) return; // 변환 실패
+ * // offset.x, offset.y는 화면 픽셀 좌표
+ * ```
  */
 export declare const computeMarkerOffset: (markerData: KonvaCanvasData<any>, controller: MintMapController) => Offset | null;
 /**
  * Point-in-Polygon 알고리즘
+ *
+ * Ray Casting 알고리즘을 사용하여 점이 폴리곤 내부에 있는지 확인합니다.
+ *
+ * @param point 확인할 점의 좌표
+ * @param polygon 폴리곤 좌표 배열 (각 요소는 [x, y] 형식)
+ * @returns 점이 폴리곤 내부에 있으면 true, 아니면 false
+ *
+ * @remarks
+ * - **알고리즘**: Ray Casting (Ray Crossing)
+ * - **성능**: O(n), n은 폴리곤의 좌표 수
+ * - **경계 처리**: 경계선 위의 점은 내부로 간주
+ *
+ * @example
+ * ```typescript
+ * const point = { x: 100, y: 200 };
+ * const polygon = [[0, 0], [100, 0], [100, 100], [0, 100]];
+ * const isInside = isPointInPolygon(point, polygon);
+ * ```
  */
 export declare const isPointInPolygon: (point: Offset, polygon: number[][]) => boolean;
 /**
  * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
  *
- * 로직:
- * 1. 외부 폴리곤(첫 번째): 내부에 있어야 함
- * 2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
+ * 점이 폴리곤 내부에 있는지 확인합니다. 도넛 폴리곤(구멍이 있는 폴리곤)을 지원합니다.
+ *
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param polygonData 폴리곤 데이터
+ * @param getPolygonOffsets 폴리곤 좌표 변환 함수
+ * @returns 점이 폴리곤 내부에 있으면 true, 아니면 false
  *
- * 중요: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됨
+ * @remarks
+ * - **도넛 폴리곤 처리** (isDonutPolygon === true):
+ *   1. 외부 폴리곤(첫 번째): 내부에 있어야 함
+ *   2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
+ * - **일반 폴리곤 처리**: Point-in-Polygon 알고리즘 사용
+ * - **성능**: O(n), n은 폴리곤의 총 좌표 수
+ *
+ * **중요**: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됩니다.
  * - 도넛 폴리곤 A: isDonutPolygon=true
  * - 내부 폴리곤 B: isDonutPolygon=false (별도 데이터)
+ *
+ * @example
+ * ```typescript
+ * const isHit = isPointInPolygonData(
+ *   clickedOffset,
+ *   polygonData,
+ *   getOrComputePolygonOffsets
+ * );
+ * ```
  */
 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 영역에서 제외됩니다.
+ *
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param markerData 마커 데이터
+ * @param getMarkerOffset 마커 좌표 변환 함수
+ * @returns 점이 마커 영역 내부에 있으면 true, 아니면 false
+ *
+ * @remarks
+ * - **꼬리 제외**: 꼬리(tail)는 Hit Test 영역에서 제외됩니다
+ *   - markerOffset.y는 마커 최하단(꼬리 끝) 좌표
+ *   - boxHeight는 마커 본체만 포함 (꼬리 제외)
+ *   - tailHeight만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+ * - **성능**: O(1) - 단순 사각형 영역 체크
+ *
+ * @example
+ * ```typescript
+ * const isHit = isPointInMarkerData(
+ *   clickedOffset,
+ *   markerData,
+ *   getOrComputeMarkerOffset
+ * );
+ * ```
  */
 export declare const isPointInMarkerData: (clickedOffset: Offset, markerData: KonvaCanvasData<any>, getMarkerOffset: (data: KonvaCanvasData<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} 계산된 텍스트 박스의 너비
+ * Canvas 2D Context의 measureText()를 사용하여 텍스트의 실제 너비를 계산하고,
+ * 패딩과 최소 너비를 고려하여 최종 너비를 반환합니다.
+ *
+ * @param params 파라미터 객체
+ * @param params.text 측정할 텍스트
+ * @param params.fontConfig 폰트 설정 (예: 'bold 16px Arial')
+ * @param params.padding 텍스트 박스에 적용할 패딩 값 (px)
+ * @param params.minWidth 최소 너비 (px)
+ * @returns 계산된 텍스트 박스의 너비 (px)
+ *
+ * @remarks
+ * - 성능: O(1) - 단일 텍스트 측정
+ * - 임시 Canvas를 사용하여 정확한 너비 측정
+ *
+ * @example
+ * ```typescript
+ * const width = calculateTextBoxWidth({
+ *   text: "Hello World",
+ *   fontConfig: 'bold 16px Arial',
+ *   padding: 20,
+ *   minWidth: 60
+ * });
+ * ```
  */
 export declare const calculateTextBoxWidth: ({ text, fontConfig, padding, minWidth, }: {
     text: string;

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

@@ -8,6 +8,30 @@ require('../../../types/MapEventTypes.js');
 
 /**
  * 폴리곤 offset 계산
+ *
+ * GeoJSON MultiPolygon 형식의 위경도 좌표를 화면 픽셀 좌표로 변환합니다.
+ *
+ * @param polygonData 폴리곤 데이터 (paths 필드 필수)
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 배열 (4차원 배열) 또는 null (변환 실패 시)
+ *
+ * @remarks
+ * - 반환 형식: [MultiPolygon][Polygon][Point][x/y]
+ * - 성능: O(n), n은 폴리곤의 총 좌표 수
+ * - GeoJSON MultiPolygon 형식 지원
+ *
+ * @example
+ * ```typescript
+ * const offsets = computePolygonOffsets(polygonData, controller);
+ * if (!offsets) return; // 변환 실패
+ *
+ * // offsets 구조: [MultiPolygon][Polygon][Point][x/y]
+ * for (const multiPolygon of offsets) {
+ *   for (const polygon of multiPolygon) {
+ *     // polygon은 [Point][x/y] 배열
+ *   }
+ * }
+ * ```
  */
 
 var computePolygonOffsets = function (polygonData, controller) {
@@ -44,6 +68,23 @@ var computePolygonOffsets = function (polygonData, controller) {
 };
 /**
  * 마커 offset 계산
+ *
+ * 마커의 위경도 좌표를 화면 픽셀 좌표로 변환합니다.
+ *
+ * @param markerData 마커 데이터 (position 필드 필수)
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 (Offset) 또는 null (변환 실패 시)
+ *
+ * @remarks
+ * - 반환된 좌표는 마커의 중심점 (x, y)
+ * - 성능: O(1) - 단일 좌표 변환
+ *
+ * @example
+ * ```typescript
+ * const offset = computeMarkerOffset(markerData, controller);
+ * if (!offset) return; // 변환 실패
+ * // offset.x, offset.y는 화면 픽셀 좌표
+ * ```
  */
 
 var computeMarkerOffset = function (markerData, controller) {
@@ -55,6 +96,24 @@ var computeMarkerOffset = function (markerData, controller) {
 };
 /**
  * Point-in-Polygon 알고리즘
+ *
+ * Ray Casting 알고리즘을 사용하여 점이 폴리곤 내부에 있는지 확인합니다.
+ *
+ * @param point 확인할 점의 좌표
+ * @param polygon 폴리곤 좌표 배열 (각 요소는 [x, y] 형식)
+ * @returns 점이 폴리곤 내부에 있으면 true, 아니면 false
+ *
+ * @remarks
+ * - **알고리즘**: Ray Casting (Ray Crossing)
+ * - **성능**: O(n), n은 폴리곤의 좌표 수
+ * - **경계 처리**: 경계선 위의 점은 내부로 간주
+ *
+ * @example
+ * ```typescript
+ * const point = { x: 100, y: 200 };
+ * const polygon = [[0, 0], [100, 0], [100, 100], [0, 100]];
+ * const isInside = isPointInPolygon(point, polygon);
+ * ```
  */
 
 var isPointInPolygon = function (point, polygon) {
@@ -74,13 +133,32 @@ var isPointInPolygon = function (point, polygon) {
 /**
  * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
  *
- * 로직:
- * 1. 외부 폴리곤(첫 번째): 내부에 있어야 함
- * 2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
+ * 점이 폴리곤 내부에 있는지 확인합니다. 도넛 폴리곤(구멍이 있는 폴리곤)을 지원합니다.
+ *
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param polygonData 폴리곤 데이터
+ * @param getPolygonOffsets 폴리곤 좌표 변환 함수
+ * @returns 점이 폴리곤 내부에 있으면 true, 아니면 false
  *
- * 중요: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됨
+ * @remarks
+ * - **도넛 폴리곤 처리** (isDonutPolygon === true):
+ *   1. 외부 폴리곤(첫 번째): 내부에 있어야 함
+ *   2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
+ * - **일반 폴리곤 처리**: Point-in-Polygon 알고리즘 사용
+ * - **성능**: O(n), n은 폴리곤의 총 좌표 수
+ *
+ * **중요**: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됩니다.
  * - 도넛 폴리곤 A: isDonutPolygon=true
  * - 내부 폴리곤 B: isDonutPolygon=false (별도 데이터)
+ *
+ * @example
+ * ```typescript
+ * const isHit = isPointInPolygonData(
+ *   clickedOffset,
+ *   polygonData,
+ *   getOrComputePolygonOffsets
+ * );
+ * ```
  */
 
 var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffsets) {
@@ -145,10 +223,29 @@ var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffse
 /**
  * 마커 히트 테스트 (클릭/hover 영역 체크)
  *
- * 🎯 중요: 꼬리(tail)는 Hit Test 영역에서 제외됩니다!
- * - markerOffset.y는 마커 최하단(꼬리 끝) 좌표
- * - boxHeight는 마커 본체만 포함 (꼬리 제외)
- * - tailHeight만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+ * 점이 마커의 클릭/호버 영역 내부에 있는지 확인합니다.
+ * 마커의 꼬리(tail)는 Hit Test 영역에서 제외됩니다.
+ *
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param markerData 마커 데이터
+ * @param getMarkerOffset 마커 좌표 변환 함수
+ * @returns 점이 마커 영역 내부에 있으면 true, 아니면 false
+ *
+ * @remarks
+ * - **꼬리 제외**: 꼬리(tail)는 Hit Test 영역에서 제외됩니다
+ *   - markerOffset.y는 마커 최하단(꼬리 끝) 좌표
+ *   - boxHeight는 마커 본체만 포함 (꼬리 제외)
+ *   - tailHeight만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+ * - **성능**: O(1) - 단순 사각형 영역 체크
+ *
+ * @example
+ * ```typescript
+ * const isHit = isPointInMarkerData(
+ *   clickedOffset,
+ *   markerData,
+ *   getOrComputeMarkerOffset
+ * );
+ * ```
  */
 
 var isPointInMarkerData = function (clickedOffset, markerData, getMarkerOffset) {
@@ -185,12 +282,29 @@ 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 Context의 measureText()를 사용하여 텍스트의 실제 너비를 계산하고,
+ * 패딩과 최소 너비를 고려하여 최종 너비를 반환합니다.
+ *
+ * @param params 파라미터 객체
+ * @param params.text 측정할 텍스트
+ * @param params.fontConfig 폰트 설정 (예: 'bold 16px Arial')
+ * @param params.padding 텍스트 박스에 적용할 패딩 값 (px)
+ * @param params.minWidth 최소 너비 (px)
+ * @returns 계산된 텍스트 박스의 너비 (px)
+ *
+ * @remarks
+ * - 성능: O(1) - 단일 텍스트 측정
+ * - 임시 Canvas를 사용하여 정확한 너비 측정
+ *
+ * @example
+ * ```typescript
+ * const width = calculateTextBoxWidth({
+ *   text: "Hello World",
+ *   fontConfig: 'bold 16px Arial',
+ *   padding: 20,
+ *   minWidth: 60
+ * });
+ * ```
  */
 
 var calculateTextBoxWidth = function (_a) {

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

@@ -0,0 +1,72 @@
+import { MutableRefObject } from "react";
+import { KonvaCanvasData } from "./types";
+/**
+ * 뷰포트 영역 (화면에 보이는 영역)
+ */
+export interface ViewportBounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+/**
+ * 바운딩 박스 (마커/폴리곤의 최소/최대 좌표)
+ */
+export interface BoundingBox {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/**
+ * 현재 뷰포트 영역 계산
+ *
+ * Konva Stage의 크기와 컬링 마진을 기반으로 뷰포트 경계를 계산합니다.
+ *
+ * @param stage Konva Stage 인스턴스 (width, height 메서드 제공)
+ * @param cullingMargin 컬링 여유 공간 (px)
+ * @param viewportRef 뷰포트 경계를 저장할 ref
+ *
+ * @remarks
+ * - 화면 밖 cullingMargin만큼의 영역까지 포함하여 계산
+ * - 스크롤 시 부드러운 전환을 위해 여유 공간 포함
+ *
+ * @example
+ * ```typescript
+ * updateViewport(stageRef.current, cullingMargin, viewportRef);
+ * ```
+ */
+export declare const updateViewport: (stage: {
+    width: () => number;
+    height: () => number;
+} | null, cullingMargin: number, viewportRef: MutableRefObject<ViewportBounds | null>) => void;
+/**
+ * 아이템이 현재 뷰포트 안에 있는지 확인 (바운딩 박스 캐싱)
+ *
+ * 뷰포트 컬링을 위한 함수입니다. 바운딩 박스와 뷰포트 경계의 교차를 확인합니다.
+ * 바운딩 박스는 캐시되어 성능을 최적화합니다.
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param item 확인할 아이템
+ * @param enableViewportCulling 뷰포트 컬링 활성화 여부
+ * @param viewportRef 뷰포트 경계 ref
+ * @param boundingBoxCacheRef 바운딩 박스 캐시 ref
+ * @param computeBoundingBox 바운딩 박스 계산 함수
+ * @returns 뷰포트 안에 있으면 true, 아니면 false
+ *
+ * @remarks
+ * - 성능: O(1) (캐시 히트 시) 또는 O(바운딩 박스 계산 비용) (캐시 미스 시)
+ * - 바운딩 박스는 자동으로 캐시되어 재사용됨
+ *
+ * @example
+ * ```typescript
+ * const isVisible = isInViewport(
+ *   item,
+ *   enableViewportCulling,
+ *   viewportRef,
+ *   boundingBoxCacheRef,
+ *   computeBoundingBox
+ * );
+ * ```
+ */
+export declare const isInViewport: <T>(item: KonvaCanvasData<T>, enableViewportCulling: boolean, viewportRef: MutableRefObject<ViewportBounds | null>, boundingBoxCacheRef: MutableRefObject<Map<string, BoundingBox>>, computeBoundingBox: (item: KonvaCanvasData<T>) => BoundingBox | null) => boolean;

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

@@ -0,0 +1,81 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * 현재 뷰포트 영역 계산
+ *
+ * Konva Stage의 크기와 컬링 마진을 기반으로 뷰포트 경계를 계산합니다.
+ *
+ * @param stage Konva Stage 인스턴스 (width, height 메서드 제공)
+ * @param cullingMargin 컬링 여유 공간 (px)
+ * @param viewportRef 뷰포트 경계를 저장할 ref
+ *
+ * @remarks
+ * - 화면 밖 cullingMargin만큼의 영역까지 포함하여 계산
+ * - 스크롤 시 부드러운 전환을 위해 여유 공간 포함
+ *
+ * @example
+ * ```typescript
+ * updateViewport(stageRef.current, cullingMargin, viewportRef);
+ * ```
+ */
+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 enableViewportCulling 뷰포트 컬링 활성화 여부
+ * @param viewportRef 뷰포트 경계 ref
+ * @param boundingBoxCacheRef 바운딩 박스 캐시 ref
+ * @param computeBoundingBox 바운딩 박스 계산 함수
+ * @returns 뷰포트 안에 있으면 true, 아니면 false
+ *
+ * @remarks
+ * - 성능: O(1) (캐시 히트 시) 또는 O(바운딩 박스 계산 비용) (캐시 미스 시)
+ * - 바운딩 박스는 자동으로 캐시되어 재사용됨
+ *
+ * @example
+ * ```typescript
+ * const isVisible = isInViewport(
+ *   item,
+ *   enableViewportCulling,
+ *   viewportRef,
+ *   boundingBoxCacheRef,
+ *   computeBoundingBox
+ * );
+ * ```
+ */
+
+var isInViewport = function (item, enableViewportCulling, viewportRef, boundingBoxCacheRef, computeBoundingBox) {
+  if (!enableViewportCulling || !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;