@mint-ui/map 1.2.0-test.5 → 1.2.0-test.51

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

@@ -0,0 +1,77 @@
+/**
+ * 공간 인덱스 그리드 셀 크기 (픽셀 단위)
+ *
+ * @default 100
+ *
+ * @remarks
+ * 셀 크기는 평균 마커 크기의 1.5~2배가 적절합니다.
+ * - 마커가 50px 이하: 50px 권장
+ * - 마커가 60-80px: 100px 권장 (현재 설정)
+ * - 마커가 100px 이상: 150-200px 권장
+ *
+ * 셀 크기가 너무 작으면:
+ * - 한 마커가 여러 셀에 등록되어 메모리 사용량 증가
+ * - 인덱스 빌드 비용 증가
+ *
+ * 셀 크기가 너무 크면:
+ * - 한 셀에 많은 마커가 들어가서 Hit Test 시 후보 항목이 많아짐
+ * - Hit Test 성능 저하
+ */
+export declare const SPATIAL_GRID_CELL_SIZE = 100;
+/**
+ * 뷰포트 컬링 여유 공간 (픽셀 단위)
+ *
+ * @default 100
+ */
+export declare const DEFAULT_CULLING_MARGIN = 100;
+/**
+ * LRU 캐시 최대 항목 수
+ *
+ * @default 30000
+ */
+export declare const DEFAULT_MAX_CACHE_SIZE = 30000;
+/**
+ * LRU Cache (Least Recently Used)
+ *
+ * 좌표 변환 결과를 캐싱하기 위한 캐시 구현
+ *
+ * @template K 캐시 키 타입
+ * @template V 캐시 값 타입
+ */
+export declare class LRUCache<K, V> {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    clear(): void;
+    size(): number;
+    has(key: K): boolean;
+}
+/**
+ * Spatial Hash Grid (공간 해시 그리드)
+ *
+ * 빠른 Hit Test를 위한 그리드 기반 공간 인덱싱 자료구조
+ *
+ * @template T 인덱싱할 항목 타입
+ */
+export declare class SpatialHashGrid<T> {
+    private cellSize;
+    private grid;
+    private itemToCells;
+    constructor(cellSize?: number);
+    private getCellKey;
+    private getCellsForBounds;
+    insert(item: T, minX: number, minY: number, maxX: number, maxY: number): void;
+    remove(item: T): void;
+    update(item: T, minX: number, minY: number, maxX: number, maxY: number): void;
+    queryPoint(x: number, y: number): T[];
+    queryBounds(minX: number, minY: number, maxX: number, maxY: number): T[];
+    has(item: T): boolean;
+    clear(): void;
+    stats(): {
+        totalCells: number;
+        totalItems: number;
+        avgItemsPerCell: number;
+    };
+}

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

@@ -0,0 +1,262 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * 공간 인덱스 그리드 셀 크기 (픽셀 단위)
+ *
+ * @default 100
+ *
+ * @remarks
+ * 셀 크기는 평균 마커 크기의 1.5~2배가 적절합니다.
+ * - 마커가 50px 이하: 50px 권장
+ * - 마커가 60-80px: 100px 권장 (현재 설정)
+ * - 마커가 100px 이상: 150-200px 권장
+ *
+ * 셀 크기가 너무 작으면:
+ * - 한 마커가 여러 셀에 등록되어 메모리 사용량 증가
+ * - 인덱스 빌드 비용 증가
+ *
+ * 셀 크기가 너무 크면:
+ * - 한 셀에 많은 마커가 들어가서 Hit Test 시 후보 항목이 많아짐
+ * - Hit Test 성능 저하
+ */
+var SPATIAL_GRID_CELL_SIZE = 100;
+/**
+ * 뷰포트 컬링 여유 공간 (픽셀 단위)
+ *
+ * @default 100
+ */
+
+var DEFAULT_CULLING_MARGIN = 100;
+/**
+ * LRU 캐시 최대 항목 수
+ *
+ * @default 30000
+ */
+
+var DEFAULT_MAX_CACHE_SIZE = 30000;
+/**
+ * LRU Cache (Least Recently Used)
+ *
+ * 좌표 변환 결과를 캐싱하기 위한 캐시 구현
+ *
+ * @template K 캐시 키 타입
+ * @template V 캐시 값 타입
+ */
+
+var LRUCache =
+/** @class */
+function () {
+  function LRUCache(maxSize) {
+    if (maxSize === void 0) {
+      maxSize = 10000;
+    }
+
+    this.cache = new Map();
+    this.maxSize = maxSize;
+  } // 캐시에서 값 조회
+
+
+  LRUCache.prototype.get = function (key) {
+    return this.cache.get(key);
+  }; // 캐시에 값 저장 (FIFO eviction)
+
+
+  LRUCache.prototype.set = function (key, value) {
+    var exists = this.cache.has(key);
+
+    if (exists) {
+      this.cache.set(key, value);
+      return;
+    }
+
+    if (this.cache.size >= this.maxSize) {
+      var firstKey = this.cache.keys().next().value;
+
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+
+    this.cache.set(key, value);
+  }; // 캐시 초기화
+
+
+  LRUCache.prototype.clear = function () {
+    this.cache.clear();
+  }; // 캐시 크기 반환
+
+
+  LRUCache.prototype.size = function () {
+    return this.cache.size;
+  }; // 키 존재 여부 확인
+
+
+  LRUCache.prototype.has = function (key) {
+    return this.cache.has(key);
+  };
+
+  return LRUCache;
+}();
+/**
+ * Spatial Hash Grid (공간 해시 그리드)
+ *
+ * 빠른 Hit Test를 위한 그리드 기반 공간 인덱싱 자료구조
+ *
+ * @template T 인덱싱할 항목 타입
+ */
+
+var SpatialHashGrid =
+/** @class */
+function () {
+  function SpatialHashGrid(cellSize) {
+    if (cellSize === void 0) {
+      cellSize = SPATIAL_GRID_CELL_SIZE;
+    }
+
+    this.cellSize = cellSize;
+    this.grid = new Map();
+    this.itemToCells = new Map();
+  } // 셀 키 생성 (x, y 좌표 → 그리드 셀 ID)
+
+
+  SpatialHashGrid.prototype.getCellKey = function (x, y) {
+    // 좌표를 셀 크기로 나눈 몫으로 셀 인덱스 계산
+    var cellX = Math.floor(x / this.cellSize);
+    var cellY = Math.floor(y / this.cellSize);
+    return "".concat(cellX, ",").concat(cellY);
+  }; // 바운딩 박스가 걸치는 모든 셀 키 배열 반환
+
+
+  SpatialHashGrid.prototype.getCellsForBounds = function (minX, minY, maxX, maxY) {
+    var cells = []; // 바운딩 박스가 걸치는 셀 범위 계산
+
+    var startCellX = Math.floor(minX / this.cellSize);
+    var startCellY = Math.floor(minY / this.cellSize);
+    var endCellX = Math.floor(maxX / this.cellSize);
+    var endCellY = Math.floor(maxY / this.cellSize); // 바운딩 박스가 걸치는 모든 셀을 배열에 추가
+
+    for (var x = startCellX; x <= endCellX; x++) {
+      for (var y = startCellY; y <= endCellY; y++) {
+        cells.push("".concat(x, ",").concat(y));
+      }
+    }
+
+    return cells;
+  }; // 항목 추가 (바운딩 박스 기반, 중복 삽입 방지)
+
+
+  SpatialHashGrid.prototype.insert = function (item, minX, minY, maxX, maxY) {
+    // 기존 항목 제거 (중복 삽입 방지: 같은 항목을 여러 번 insert 해도 안전)
+    this.remove(item); // 바운딩 박스가 걸치는 모든 셀에 항목 등록
+
+    var cells = this.getCellsForBounds(minX, minY, maxX, maxY);
+    this.itemToCells.set(item, cells); // 항목과 셀의 매핑 저장 (제거 시 필요)
+
+    for (var _i = 0, cells_1 = cells; _i < cells_1.length; _i++) {
+      var cell = cells_1[_i];
+
+      if (!this.grid.has(cell)) {
+        this.grid.set(cell, []);
+      }
+
+      this.grid.get(cell).push(item);
+    }
+  }; // 항목 제거 (모든 셀에서 참조 제거)
+
+
+  SpatialHashGrid.prototype.remove = function (item) {
+    var prevCells = this.itemToCells.get(item);
+    if (!prevCells) return; // 항목이 등록된 모든 셀에서 참조 제거 (메모리 누수 방지)
+
+    for (var _i = 0, prevCells_1 = prevCells; _i < prevCells_1.length; _i++) {
+      var cell = prevCells_1[_i];
+      var cellItems = this.grid.get(cell);
+
+      if (cellItems) {
+        var index = cellItems.indexOf(item);
+
+        if (index !== -1) {
+          cellItems.splice(index, 1);
+        } // 빈 셀 정리 (메모리 효율: 사용하지 않는 셀 제거)
+
+
+        if (cellItems.length === 0) {
+          this.grid.delete(cell);
+        }
+      }
+    } // 항목과 셀의 매핑 제거
+
+
+    this.itemToCells.delete(item);
+  }; // 항목 위치 업데이트 (remove + insert)
+
+
+  SpatialHashGrid.prototype.update = function (item, minX, minY, maxX, maxY) {
+    this.insert(item, minX, minY, maxX, maxY);
+  }; // 점 주변의 항목 조회 (Hit Test용)
+
+
+  SpatialHashGrid.prototype.queryPoint = function (x, y) {
+    // 클릭 위치가 속한 셀의 모든 항목 조회 (O(1) 수준의 빠른 조회)
+    var cellKey = this.getCellKey(x, y);
+    var items = this.grid.get(cellKey); // 빈 배열 재사용 (메모리 할당 최소화)
+
+    return items || [];
+  }; // 영역 내 항목 조회 (Viewport Culling용)
+
+
+  SpatialHashGrid.prototype.queryBounds = function (minX, minY, maxX, maxY) {
+    // 영역이 걸치는 모든 셀 찾기
+    var cells = this.getCellsForBounds(minX, minY, maxX, maxY);
+    var results = new Set(); // 중복 제거를 위해 Set 사용
+    // 각 셀의 모든 항목을 결과에 추가
+
+    for (var _i = 0, cells_2 = cells; _i < cells_2.length; _i++) {
+      var cell = cells_2[_i];
+      var items = this.grid.get(cell);
+
+      if (items) {
+        for (var _a = 0, items_1 = items; _a < items_1.length; _a++) {
+          var item = items_1[_a];
+          results.add(item); // Set이므로 중복 자동 제거
+        }
+      }
+    }
+
+    return Array.from(results);
+  }; // 항목 존재 여부 확인
+
+
+  SpatialHashGrid.prototype.has = function (item) {
+    return this.itemToCells.has(item);
+  }; // 전체 초기화
+
+
+  SpatialHashGrid.prototype.clear = function () {
+    this.grid.clear();
+    this.itemToCells.clear();
+  }; // 통계 정보 반환
+
+
+  SpatialHashGrid.prototype.stats = function () {
+    var totalCellItems = 0;
+    this.grid.forEach(function (items) {
+      totalCellItems += items.length;
+    });
+    return {
+      totalCells: this.grid.size,
+      totalItems: this.itemToCells.size,
+      avgItemsPerCell: this.grid.size > 0 ? totalCellItems / this.grid.size : 0
+    };
+  };
+
+  return SpatialHashGrid;
+}();
+
+exports.DEFAULT_CULLING_MARGIN = DEFAULT_CULLING_MARGIN;
+exports.DEFAULT_MAX_CACHE_SIZE = DEFAULT_MAX_CACHE_SIZE;
+exports.LRUCache = LRUCache;
+exports.SPATIAL_GRID_CELL_SIZE = SPATIAL_GRID_CELL_SIZE;
+exports.SpatialHashGrid = SpatialHashGrid;

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

@@ -0,0 +1,127 @@
+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[][][][];
+}
+/**
+ * 캔버스 마커/폴리곤의 기본 필수 속성
+ */
+export interface CanvasOption {
+    id: string;
+    position: Position;
+    boxWidth?: number;
+    boxHeight?: number;
+    tailHeight?: number;
+    paths?: Paths;
+    isDonutPolygon?: boolean;
+    /** 렌더링 오프셋 X (픽셀 단위, 기본값: 0) */
+    offsetX?: number;
+    /** 렌더링 오프셋 Y (픽셀 단위, 기본값: 0) */
+    offsetY?: number;
+}
+/**
+ * 서버 데이터와 캔버스 옵션을 결합한 타입
+ *
+ * @template T 서버에서 받은 원본 데이터 타입
+ *
+ * @remarks
+ * 서버 데이터의 필드가 CanvasOption과 충돌하는 경우 (예: id, position 등),
+ * 변환 시 명시적으로 매핑해야 합니다. createCanvasData 헬퍼 함수를 사용하세요.
+ *
+ * @example
+ * ```typescript
+ * // 서버 데이터에 id가 number 타입인 경우
+ * interface ServerData {
+ *   id: number;
+ *   name: string;
+ * }
+ *
+ * // ❌ 잘못된 사용 (타입 에러 발생)
+ * const data: CanvasData<ServerData> = {
+ *   ...serverData,
+ *   id: String(serverData.id), // 명시적 변환 필요
+ *   position: new Position(lat, lng)
+ * };
+ *
+ * // ✅ 올바른 사용 (헬퍼 함수 사용)
+ * const data = createCanvasData(serverData, {
+ *   id: String(serverData.id),
+ *   position: new Position(lat, lng)
+ * });
+ * ```
+ */
+export declare type CanvasData<T = {}> = T & CanvasOption;
+/**
+ * 서버 데이터를 CanvasData로 변환하는 헬퍼 함수들
+ *
+ * @see createCanvasData, createCanvasDataArray in ./utils.ts
+ */
+export { createCanvasData, createCanvasDataArray } from './utils';
+/**
+ * 렌더링 유틸리티 함수들 (좌표 변환)
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ */
+export interface RenderUtils<T> {
+    getOrComputePolygonOffsets: (polygonData: CanvasData<T>) => number[][][][] | null;
+    getOrComputeMarkerOffset: (markerData: CanvasData<T>) => Offset | null;
+}
+/**
+ * 커스텀 렌더링 함수 파라미터 - Base Layer
+ */
+export interface RenderBaseParams<T> {
+    ctx: CanvasRenderingContext2D;
+    items: CanvasData<T>[];
+    selectedIds: Set<string>;
+    hoveredItem?: CanvasData<T> | null;
+    selectedItem?: CanvasData<T> | null;
+    utils: RenderUtils<T>;
+}
+/**
+ * 커스텀 렌더링 함수 타입 - Base Layer
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ */
+export declare type CustomRenderBase<T> = (params: RenderBaseParams<T>) => void;
+/**
+ * 커스텀 렌더링 함수 파라미터 - Animation Layer
+ */
+export interface RenderAnimationParams<T> {
+    layer: Konva.Layer;
+    selectedIds: Set<string>;
+    items: CanvasData<T>[];
+    utils: RenderUtils<T>;
+}
+/**
+ * 커스텀 렌더링 함수 타입 - Animation Layer (선택)
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ */
+export declare type CustomRenderAnimation<T> = (params: RenderAnimationParams<T>) => void;
+/**
+ * 커스텀 렌더링 함수 파라미터 - Event Layer
+ */
+export interface RenderEventParams<T> {
+    ctx: CanvasRenderingContext2D;
+    hoveredItem: CanvasData<T> | null;
+    utils: RenderUtils<T>;
+    selectedItems?: CanvasData<T>[];
+    selectedItem?: CanvasData<T> | null;
+}
+/**
+ * 커스텀 렌더링 함수 타입 - Event Layer
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ */
+export declare type CustomRenderEvent<T> = (params: RenderEventParams<T>) => void;

package/dist/components/mint-map/core/advanced/{woongCanvas/shared → shared}/types.js

@@ -2,9 +2,10 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var utils = require('./utils.js');
+
 /**
  * 캔버스 데이터 타입 Enum
- * 마커인지 폴리곤인지 구분하는 상수
  */
 exports.CanvasDataType = void 0;
 
@@ -12,3 +13,6 @@ exports.CanvasDataType = void 0;
   CanvasDataType["MARKER"] = "MARKER";
   CanvasDataType["POLYGON"] = "POLYGON";
 })(exports.CanvasDataType || (exports.CanvasDataType = {}));
+
+exports.createCanvasData = utils.createCanvasData;
+exports.createCanvasDataArray = utils.createCanvasDataArray;

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

@@ -0,0 +1,130 @@
+import { Offset } from "../../../types";
+import { MintMapController } from "../../MintMapController";
+import { CanvasData, CanvasOption } from "./types";
+/**
+ * 폴리곤 좌표 변환 (위경도 → 화면 좌표)
+ *
+ * @param polygonData 폴리곤 데이터
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 배열 (4차원 배열) 또는 null
+ */
+export declare const computePolygonOffsets: (polygonData: CanvasData<any>, controller: MintMapController) => number[][][][] | null;
+/**
+ * 마커 좌표 변환 (위경도 → 화면 좌표)
+ *
+ * @param markerData 마커 데이터
+ * @param controller MintMapController 인스턴스
+ * @returns 변환된 화면 좌표 또는 null
+ */
+export declare const computeMarkerOffset: (markerData: CanvasData<any>, controller: MintMapController) => Offset | null;
+/**
+ * Point-in-Polygon 알고리즘 (Ray Casting)
+ *
+ * @param point 확인할 점의 좌표
+ * @param polygon 폴리곤 좌표 배열
+ * @returns 점이 폴리곤 내부에 있으면 true
+ */
+export declare const isPointInPolygon: (point: Offset, polygon: number[][]) => boolean;
+/**
+ * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
+ *
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param polygonData 폴리곤 데이터
+ * @param getPolygonOffsets 폴리곤 좌표 변환 함수
+ * @returns 점이 폴리곤 내부에 있으면 true
+ */
+export declare const isPointInPolygonData: (clickedOffset: Offset, polygonData: CanvasData<any>, getPolygonOffsets: (data: CanvasData<any>) => number[][][][] | null) => boolean;
+/**
+ * 마커 히트 테스트 (꼬리 제외, 오프셋 지원)
+ *
+ * @param clickedOffset 클릭/마우스 위치 좌표
+ * @param markerData 마커 데이터
+ * @param getMarkerOffset 마커 좌표 변환 함수
+ * @returns 점이 마커 영역 내부에 있으면 true
+ */
+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 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;
+    fontConfig: string;
+    padding: number;
+    minWidth: number;
+}) => number;
+/**
+ * 서버 데이터를 CanvasData로 변환하는 헬퍼 함수
+ *
+ * 서버 데이터의 필드가 CanvasOption과 충돌하는 경우 (예: id, position 등),
+ * 이 함수를 사용하여 명시적으로 매핑할 수 있습니다.
+ *
+ * @template T 서버에서 받은 원본 데이터 타입
+ * @param serverData 서버에서 받은 원본 데이터
+ * @param canvasOptions CanvasOption 필드들 (충돌하는 필드는 여기서 명시적으로 지정)
+ * @returns CanvasData<T> 타입의 데이터
+ *
+ * @example
+ * ```typescript
+ * interface ServerData {
+ *   id: number;  // CanvasOption의 id와 충돌
+ *   name: string;
+ * }
+ *
+ * const serverData: ServerData = { id: 123, name: "Test" };
+ *
+ * // ✅ 올바른 사용
+ * const canvasData = createCanvasData(serverData, {
+ *   id: String(serverData.id),  // 명시적으로 변환
+ *   position: new Position(37.5, 127.0)
+ * });
+ *
+ * // canvasData는 CanvasData<ServerData> 타입이며:
+ * // - id: string (CanvasOption의 id)
+ * // - name: string (서버 데이터의 name)
+ * // - position: Position (CanvasOption의 position)
+ * ```
+ */
+export declare function createCanvasData<T extends Record<string, any>>(serverData: T, canvasOptions: CanvasOption): CanvasData<T>;
+/**
+ * 서버 데이터 배열을 CanvasData 배열로 변환하는 헬퍼 함수
+ *
+ * 서버 데이터 배열의 각 항목을 CanvasData로 변환합니다.
+ * 각 항목마다 다른 CanvasOption을 적용할 수 있습니다.
+ *
+ * @template T 서버에서 받은 원본 데이터 타입
+ * @param serverDataArray 서버에서 받은 원본 데이터 배열
+ * @param getCanvasOptions 각 항목에 대해 CanvasOption을 생성하는 함수
+ * @returns CanvasData<T>[] 타입의 데이터 배열
+ *
+ * @example
+ * ```typescript
+ * interface ServerData {
+ *   id: number;  // CanvasOption의 id와 충돌
+ *   name: string;
+ *   lat: number;
+ *   lng: number;
+ * }
+ *
+ * const serverDataArray: ServerData[] = [
+ *   { id: 1, name: "Item 1", lat: 37.5, lng: 127.0 },
+ *   { id: 2, name: "Item 2", lat: 37.6, lng: 127.1 }
+ * ];
+ *
+ * // ✅ 올바른 사용
+ * const canvasDataArray = createCanvasDataArray(serverDataArray, (item, index) => ({
+ *   id: String(item.id),  // 각 항목마다 명시적으로 변환
+ *   position: new Position(item.lat, item.lng)
+ * }));
+ *
+ * // canvasDataArray는 CanvasData<ServerData>[] 타입입니다
+ * ```
+ */
+export declare function createCanvasDataArray<T extends Record<string, any>>(serverDataArray: T[], getCanvasOptions: (serverData: T, index: number) => CanvasOption): CanvasData<T>[];