@mint-ui/map 1.2.0-test.8 → 1.2.0

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

@@ -0,0 +1,150 @@
+import Konva from 'konva';
+import { Offset, Position } from '../../../types';
+/**
+ * 캔버스 데이터 타입 Enum
+ */
+export declare enum CanvasDataType {
+    MARKER = "MARKER",
+    POLYGON = "POLYGON"
+}
+/**
+ * 폴리곤 경로 정의 (GeoJSON MultiPolygon 형식)
+ */
+export interface Paths {
+    type: string;
+    coordinates: number[][][][];
+}
+/**
+ * 마커 바운딩 박스 좌표 (위도/경도)
+ */
+export interface MarkerBoundingBox {
+    /** 왼쪽 상단 좌표 */
+    leftTop: Position;
+    /** 우측 하단 좌표 */
+    bottomRight: Position;
+}
+/**
+ * 캔버스 마커/폴리곤의 기본 필수 속성
+ */
+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;
+    /** 마커 바운딩 박스 좌표 (onMouseOver 이벤트에서만 제공됨) */
+    boundingBox?: MarkerBoundingBox;
+}
+/**
+ * 서버 데이터와 캔버스 옵션을 결합한 타입
+ *
+ * @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;
+/**
+ * 렌더링 소스 Enum
+ */
+export declare enum RenderSource {
+    BASE = "BASE",
+    EVENT = "EVENT",
+    TOP = "TOP"
+}
+/**
+ * 커스텀 렌더링 함수 파라미터 - Event Layer
+ */
+export interface RenderEventParams<T> {
+    ctx: CanvasRenderingContext2D;
+    /** topStageZIndex가 설정되어 있는지 여부 */
+    hasTopStage: boolean;
+    hoveredItem: CanvasData<T> | null;
+    /** 렌더링 소스 (BASE, EVENT, TOP) */
+    renderSource: RenderSource;
+    selectedItems?: CanvasData<T>[];
+    selectedItem?: CanvasData<T> | null;
+    utils: RenderUtils<T>;
+}
+/**
+ * 커스텀 렌더링 함수 타입 - Event Layer
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ */
+export declare type CustomRenderEvent<T> = (params: RenderEventParams<T>) => void;

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

@@ -0,0 +1,31 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils = require('./utils.js');
+
+/**
+ * 캔버스 데이터 타입 Enum
+ */
+// eslint-disable-next-line no-shadow
+exports.CanvasDataType = void 0;
+
+(function (CanvasDataType) {
+  CanvasDataType["MARKER"] = "MARKER";
+  CanvasDataType["POLYGON"] = "POLYGON";
+})(exports.CanvasDataType || (exports.CanvasDataType = {}));
+/**
+ * 렌더링 소스 Enum
+ */
+// eslint-disable-next-line no-shadow
+
+exports.RenderSource = void 0;
+
+(function (RenderSource) {
+  RenderSource["BASE"] = "BASE";
+  RenderSource["EVENT"] = "EVENT";
+  RenderSource["TOP"] = "TOP";
+})(exports.RenderSource || (exports.RenderSource = {}));
+
+exports.createCanvasData = utils.createCanvasData;
+exports.createCanvasDataArray = utils.createCanvasDataArray;

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

@@ -0,0 +1,173 @@
+import type { MarkerBoundingBox } from './types';
+import { CanvasData, CanvasOption } from './types';
+import { Offset } from '../../../types';
+import { MintMapController } from '../../MintMapController';
+/**
+ * 폴리곤 좌표 변환 (위경도 → 화면 좌표)
+ *
+ * @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: ({ fontConfig, minWidth, padding, text }: {
+    fontConfig: string;
+    minWidth: number;
+    padding: number;
+    text: string;
+}) => 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>[];
+/**
+ * 마커 바운딩 박스 좌표 계산 (위도/경도)
+ *
+ * 마커의 중심 좌표와 크기를 기반으로 현재 뷰포트에서의 바운딩 박스 좌표를 계산합니다.
+ *
+ * @param params 계산 파라미터
+ * @param params.lat 마커의 중심 위도
+ * @param params.lng 마커의 중심 경도
+ * @param params.width 마커의 너비 (픽셀 단위, boxWidth)
+ * @param params.height 마커의 높이 (픽셀 단위, boxHeight)
+ * @param params.controller MintMapController 인스턴스 (뷰포트 상태를 알기 위해 필요)
+ * @param params.tailHeight 마커 꼬리 높이 (픽셀 단위, 기본값: 0)
+ * @param params.offsetX 마커 오프셋 X (픽셀 단위, 기본값: 0)
+ * @param params.offsetY 마커 오프셋 Y (픽셀 단위, 기본값: 0)
+ * @returns 마커 바운딩 박스 좌표 (위도/경도) 또는 null
+ *
+ * @example
+ * ```typescript
+ * const boundingBox = calculateMarkerBoundingBox({
+ *   lat: 37.5665,
+ *   lng: 126.9780,
+ *   width: 100,
+ *   height: 50,
+ *   controller: mintMapController
+ * });
+ *
+ * if (boundingBox) {
+ *   console.log('왼쪽 상단:', boundingBox.leftTop);
+ *   console.log('우측 하단:', boundingBox.bottomRight);
+ * }
+ * ```
+ */
+export declare const calculateMarkerBoundingBox: (params: {
+    lat: number;
+    lng: number;
+    width: number;
+    height: number;
+    controller: MintMapController;
+    tailHeight?: number;
+    offsetX?: number;
+    offsetY?: number;
+}) => MarkerBoundingBox | null;