@mint-ui/map 1.2.0-test.2 → 1.2.0-test.21

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

@@ -0,0 +1,288 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * @fileoverview 폴리곤 렌더링을 위한 유틸리티 및 팩토리 함수
+ *
+ * 이 파일은 WoongCanvasLayer의 POLYGON 모드에서 사용하는 폴리곤 렌더링
+ * 함수들을 제공합니다. 다양한 상태(기본, 선택, 호버)에 따른 렌더링과
+ * 도넛 폴리곤(구멍이 있는 폴리곤) 지원을 포함합니다.
+ *
+ * ## 주요 기능
+ * - **폴리곤 그리기**: Canvas 2D API를 사용한 폴리곤 렌더링
+ * - **도넛 폴리곤 지원**: evenodd fill rule을 사용한 구멍 처리
+ * - **상태별 렌더링**: 기본/선택/호버 상태에 따른 색상 및 스타일 적용
+ * - **팩토리 함수**: 렌더링 함수를 쉽게 생성할 수 있는 헬퍼
+ *
+ * @version 2.2.1
+ * @since 2.0.0
+ * @author 박건웅
+ */
+
+/**
+ * 폴리곤 그리기 헬퍼 함수
+ *
+ * Canvas 2D API를 사용하여 폴리곤을 그리는 핵심 함수입니다.
+ * 도넛 폴리곤(구멍이 있는 폴리곤)도 지원합니다.
+ *
+ * @param ctx - Canvas 2D 렌더링 컨텍스트
+ * @param polygonOffsets - 변환된 폴리곤 좌표 배열
+ * @param isDonutPolygon - 도넛 폴리곤 여부
+ * @param fillColor - 채우기 색상
+ * @param strokeColor - 테두리 색상
+ * @param lineWidth - 테두리 두께
+ *
+ * @example
+ * ```typescript
+ * drawPolygon({
+ *   ctx,
+ *   polygonOffsets: [[[[100, 200], [200, 200], [200, 300], [100, 300]]]],
+ *   isDonutPolygon: false,
+ *   fillColor: 'rgba(255, 0, 0, 0.5)',
+ *   strokeColor: 'rgba(255, 0, 0, 1)',
+ *   lineWidth: 2
+ * });
+ * ```
+ */
+var drawPolygon = function (_a) {
+  var ctx = _a.ctx,
+      polygonOffsets = _a.polygonOffsets,
+      isDonutPolygon = _a.isDonutPolygon,
+      fillColor = _a.fillColor,
+      strokeColor = _a.strokeColor,
+      lineWidth = _a.lineWidth;
+
+  for (var _i = 0, polygonOffsets_1 = polygonOffsets; _i < polygonOffsets_1.length; _i++) {
+    var multiPolygon = polygonOffsets_1[_i];
+
+    if (isDonutPolygon) {
+      ctx.beginPath(); // 1. 외부 폴리곤 그리기
+
+      if (multiPolygon[0] && multiPolygon[0].length > 0) {
+        ctx.moveTo(multiPolygon[0][0][0], multiPolygon[0][0][1]);
+
+        for (var i = 1; i < multiPolygon[0].length; i++) {
+          ctx.lineTo(multiPolygon[0][i][0], multiPolygon[0][i][1]);
+        }
+
+        ctx.closePath();
+      } // 2. 내부 폴리곤 (구멍들) 그리기 - 같은 path에 추가
+
+
+      for (var j = 1; j < multiPolygon.length; j++) {
+        var innerPolygon = multiPolygon[j];
+        if (innerPolygon.length === 0) continue;
+        ctx.moveTo(innerPolygon[0][0], innerPolygon[0][1]);
+
+        for (var i = 1; i < innerPolygon.length; i++) {
+          ctx.lineTo(innerPolygon[i][0], innerPolygon[i][1]);
+        }
+
+        ctx.closePath();
+      } // 3. evenodd fill rule로 구멍 뚫기
+
+
+      ctx.fillStyle = fillColor;
+      ctx.fill('evenodd'); // 4. 외곽선 그리기
+
+      ctx.strokeStyle = strokeColor;
+      ctx.lineWidth = lineWidth;
+      ctx.stroke();
+    } else {
+      // 일반 폴리곤
+      for (var _b = 0, multiPolygon_1 = multiPolygon; _b < multiPolygon_1.length; _b++) {
+        var polygonGroup = multiPolygon_1[_b];
+        if (!polygonGroup.length) continue;
+        ctx.beginPath();
+        var firstPoint = polygonGroup[0];
+        ctx.moveTo(firstPoint[0], firstPoint[1]);
+
+        for (var i = 1; i < polygonGroup.length; i++) {
+          var point = polygonGroup[i];
+          ctx.lineTo(point[0], point[1]);
+        }
+
+        ctx.closePath();
+        ctx.fillStyle = fillColor;
+        ctx.strokeStyle = strokeColor;
+        ctx.lineWidth = lineWidth;
+        ctx.fill();
+        ctx.stroke();
+      }
+    }
+  }
+};
+/**
+ * 폴리곤 Base Layer 렌더링 함수 팩토리
+ *
+ * 기본 상태의 폴리곤들을 렌더링하는 함수를 생성합니다.
+ * 선택된 폴리곤들은 Event Layer에서 렌더링되므로 제외됩니다.
+ *
+ * @param baseFillColor - 기본 폴리곤 채우기 색상
+ * @param baseStrokeColor - 기본 폴리곤 테두리 색상
+ * @param baseLineWidth - 기본 폴리곤 테두리 두께
+ * @returns Base Layer 렌더링 함수
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ *
+ * @example
+ * ```typescript
+ * const renderBase = renderPolygonBase(
+ *   'rgba(255, 100, 100, 0.5)',  // 기본 채우기 색상
+ *   'rgba(200, 50, 50, 0.8)',    // 기본 테두리 색상
+ *   2                             // 기본 테두리 두께
+ * );
+ * ```
+ */
+
+var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth) {
+  return function (_a) {
+    var ctx = _a.ctx,
+        items = _a.items,
+        selectedIds = _a.selectedIds,
+        utils = _a.utils;
+
+    for (var _i = 0, items_1 = items; _i < items_1.length; _i++) {
+      var item = items_1[_i]; // 선택된 항목은 Event Layer에서 그림
+
+      if (selectedIds.has(item.id)) continue;
+      if (!item.paths) continue;
+      var polygonOffsets = utils.getOrComputePolygonOffsets(item);
+      if (!polygonOffsets) continue;
+      drawPolygon({
+        ctx: ctx,
+        polygonOffsets: polygonOffsets,
+        isDonutPolygon: item.isDonutPolygon || false,
+        fillColor: baseFillColor,
+        strokeColor: baseStrokeColor,
+        lineWidth: baseLineWidth
+      });
+    }
+  };
+};
+/**
+ * 폴리곤 Event Layer 렌더링 함수 팩토리
+ *
+ * 선택, 호버, 활성 상태의 폴리곤들을 렌더링하는 함수를 생성합니다.
+ * 다양한 상태에 따른 색상과 스타일을 지원하며, fallback 메커니즘을 제공합니다.
+ *
+ * ## 상태별 렌더링 우선순위
+ * 1. **Hovered**: 마우스가 올라간 폴리곤 (최우선)
+ * 2. **Active**: 마지막으로 선택된 폴리곤
+ * 3. **Selected**: 선택된 폴리곤들
+ * 4. **Base**: 기본 상태 (fallback)
+ *
+ * @param baseFillColor - 기본 폴리곤 채우기 색상 (필수, fallback용)
+ * @param baseStrokeColor - 기본 폴리곤 테두리 색상 (필수, fallback용)
+ * @param baseLineWidth - 기본 폴리곤 테두리 두께 (필수, fallback용)
+ * @param selectedFillColor - 선택된 폴리곤 채우기 색상 (선택, 기본값: baseFillColor)
+ * @param selectedStrokeColor - 선택된 폴리곤 테두리 색상 (선택, 기본값: baseStrokeColor)
+ * @param selectedLineWidth - 선택된 폴리곤 테두리 두께 (선택, 기본값: baseLineWidth)
+ * @param activeFillColor - 마지막 선택된 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+ * @param activeStrokeColor - 마지막 선택된 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+ * @param activeLineWidth - 마지막 선택된 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+ * @param hoveredFillColor - Hover 시 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+ * @param hoveredStrokeColor - Hover 시 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+ * @param hoveredLineWidth - Hover 시 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+ * @returns Event Layer 렌더링 함수
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ *
+ * @example
+ * ```typescript
+ * const renderEvent = renderPolygonEvent(
+ *   'rgba(255, 100, 100, 0.5)',  // baseFillColor
+ *   'rgba(200, 50, 50, 0.8)',    // baseStrokeColor
+ *   2,                            // baseLineWidth
+ *   'rgba(255, 193, 7, 0.7)',    // selectedFillColor
+ *   'rgba(255, 152, 0, 1)',      // selectedStrokeColor
+ *   4                             // selectedLineWidth
+ * );
+ * ```
+ */
+
+var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth, selectedFillColor, selectedStrokeColor, selectedLineWidth, activeFillColor, activeStrokeColor, activeLineWidth, hoveredFillColor, hoveredStrokeColor, hoveredLineWidth) {
+  // 기본값 설정 (base 기준)
+  var _selectedFillColor = selectedFillColor || baseFillColor;
+
+  var _selectedStrokeColor = selectedStrokeColor || baseStrokeColor;
+
+  var _selectedLineWidth = selectedLineWidth || baseLineWidth;
+
+  var _activeFillColor = activeFillColor || _selectedFillColor;
+
+  var _activeStrokeColor = activeStrokeColor || _selectedStrokeColor;
+
+  var _activeLineWidth = activeLineWidth || _selectedLineWidth;
+
+  var _hoveredFillColor = hoveredFillColor || _selectedFillColor;
+
+  var _hoveredStrokeColor = hoveredStrokeColor || _selectedStrokeColor;
+
+  var _hoveredLineWidth = hoveredLineWidth || _selectedLineWidth;
+
+  return function (_a) {
+    var ctx = _a.ctx,
+        hoveredItem = _a.hoveredItem,
+        utils = _a.utils,
+        selectedItems = _a.selectedItems,
+        selectedItem = _a.selectedItem; // 1. 선택된 항목들 그리기 (마지막 선택 항목과 호버된 항목 제외)
+
+    if (selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.length) {
+      for (var _i = 0, selectedItems_1 = selectedItems; _i < selectedItems_1.length; _i++) {
+        var item = selectedItems_1[_i]; // 마지막 선택 항목과 호버된 항목은 나중에 따로 그림
+
+        if (item.id === (selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.id) || (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) === item.id) continue;
+        if (!item.paths) continue;
+        var polygonOffsets = utils.getOrComputePolygonOffsets(item);
+        if (!polygonOffsets) continue;
+        drawPolygon({
+          ctx: ctx,
+          polygonOffsets: polygonOffsets,
+          isDonutPolygon: item.isDonutPolygon || false,
+          fillColor: _selectedFillColor,
+          strokeColor: _selectedStrokeColor,
+          lineWidth: _selectedLineWidth
+        });
+      }
+    } // 2. 마지막 선택된 항목 그리기 (호버되지 않은 경우)
+
+
+    if ((selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.paths) && (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) !== selectedItem.id) {
+      var polygonOffsets = utils.getOrComputePolygonOffsets(selectedItem);
+
+      if (polygonOffsets) {
+        drawPolygon({
+          ctx: ctx,
+          polygonOffsets: polygonOffsets,
+          isDonutPolygon: selectedItem.isDonutPolygon || false,
+          fillColor: _activeFillColor,
+          strokeColor: _activeStrokeColor,
+          lineWidth: _activeLineWidth
+        });
+      }
+    } // 3. 호버된 항목 그리기 (가장 위에 표시)
+
+
+    if (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.paths) {
+      var polygonOffsets = utils.getOrComputePolygonOffsets(hoveredItem);
+      if (!polygonOffsets) return;
+      var isSelected = selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.some(function (item) {
+        return item.id === hoveredItem.id;
+      });
+      drawPolygon({
+        ctx: ctx,
+        polygonOffsets: polygonOffsets,
+        isDonutPolygon: hoveredItem.isDonutPolygon || false,
+        fillColor: isSelected ? _activeFillColor : _hoveredFillColor,
+        strokeColor: isSelected ? _activeStrokeColor : _hoveredStrokeColor,
+        lineWidth: isSelected ? _activeLineWidth : _hoveredLineWidth
+      });
+    }
+  };
+};
+
+exports.drawPolygon = drawPolygon;
+exports.renderPolygonBase = renderPolygonBase;
+exports.renderPolygonEvent = renderPolygonEvent;

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

@@ -1,25 +1,51 @@
 import Konva from "konva";
 import { Position, Offset } from "../../../../types";
 /**
- * 폴리곤 경로 정의
+ * 캔버스 데이터 타입 Enum
+ * 마커인지 폴리곤인지 구분하는 상수
+ *
+ * @enum {string}
+ * @memberof WoongCanvasLayer
+ */
+export declare enum CanvasDataType {
+    /** 마커 타입 - 커스텀 렌더링 필요 */
+    MARKER = "MARKER",
+    /** 폴리곤 타입 - 자동 렌더링 지원 */
+    POLYGON = "POLYGON"
+}
+/**
+ * 폴리곤 경로 정의 (GeoJSON MultiPolygon 형식)
+ *
+ * @interface Paths
+ * @memberof WoongCanvasLayer
  */
 export interface Paths {
+    /** GeoJSON 타입 (MultiPolygon) */
     type: string;
+    /** 4차원 좌표 배열 [MultiPolygon][Polygon][Point][x/y] */
     coordinates: number[][][][];
 }
 /**
- * 캔버스 마커/폴리곤 기본 옵션
- */
-/**
- * 캔버스 마커/폴리곤의 기본 필수 속성
+ * Konva 캔버스 마커/폴리곤의 기본 필수 속성
  * (렌더링에 필요한 최소 정보)
+ *
+ * @interface KonvaCanvasOption
+ * @memberof WoongCanvasLayer
  */
-export interface CanvasMarkerOption {
+export interface KonvaCanvasOption {
+    /** 고유 식별자 */
     id: string;
-    position: Position[];
+    /** 지도상 위치 (위경도) */
+    position: Position;
+    /** 마커 본체 너비 (Hit Test 영역) */
     boxWidth?: number;
+    /** 마커 본체 높이 (Hit Test 영역) */
     boxHeight?: number;
+    /** 마커 꼬리 높이 (Viewport Culling용, Hit Test에서는 제외) */
+    tailHeight?: number;
+    /** 폴리곤 경로 (GeoJSON MultiPolygon) */
     paths?: Paths;
+    /** 도넛 폴리곤 여부 (구멍이 있는 폴리곤) */
     isDonutPolygon?: boolean;
 }
 /**
@@ -27,16 +53,110 @@ export interface CanvasMarkerOption {
  * @template T 서버에서 받은 원본 데이터 타입 (예: Marker, Polygon)
  * @example
  * // API에서 받은 Marker 타입을 그대로 유지하면서 캔버스 렌더링 정보 추가
- * type MarkerWithCanvas = CanvasMarkerData<Marker>
+ * type MarkerWithCanvas = KonvaCanvasData<Marker>
  * // { raId, lat, lng, buildingName, totalArea } + { id, position, boxWidth, ... }
  */
-export declare type CanvasMarkerData<T = {}> = T & CanvasMarkerOption;
+export declare type KonvaCanvasData<T = {}> = T & KonvaCanvasOption;
 /**
- * 렌더링 유틸리티 함수들
+ * 🛠️ 렌더링 유틸리티 함수들
+ *
+ * WoongCanvasLayer가 제공하는 헬퍼 함수 모음입니다.
+ * 커스텀 렌더링 함수 내에서 좌표 변환 시 사용하세요.
+ *
+ * ## 주요 기능
+ * - **자동 캐싱**: 좌표 변환 결과를 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> {
-    getOrComputePolygonOffsets: (polygonData: CanvasMarkerData<T>) => number[][][][] | null;
-    getOrComputeMarkerOffset: (markerData: CanvasMarkerData<T>) => Offset | null;
+    /**
+     * 폴리곤의 위경도 좌표를 화면 픽셀 좌표로 변환합니다.
+     *
+     * - **자동 캐싱**: 동일한 폴리곤은 캐시에서 즉시 반환 (성능 최적화)
+     * - **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;
 }
 /**
  * 커스텀 렌더링 함수 파라미터 - Base Layer
@@ -45,7 +165,7 @@ export interface RenderBaseParams<T> {
     /** Canvas 2D 렌더링 컨텍스트 (순수 Canvas API) */
     ctx: CanvasRenderingContext2D;
     /** 렌더링할 마커 데이터 배열 */
-    items: CanvasMarkerData<T>[];
+    items: KonvaCanvasData<T>[];
     /** 현재 선택된 마커 ID Set */
     selectedIds: Set<string>;
     /** 렌더링 유틸리티 함수들 */
@@ -75,7 +195,7 @@ export interface RenderAnimationParams<T> {
     /** 현재 선택된 마커 ID Set */
     selectedIds: Set<string>;
     /** 전체 마커 데이터 배열 */
-    items: CanvasMarkerData<T>[];
+    items: KonvaCanvasData<T>[];
     /** 렌더링 유틸리티 함수들 */
     utils: RenderUtils<T>;
 }
@@ -98,11 +218,13 @@ export interface RenderEventParams<T> {
     /** Canvas 2D 렌더링 컨텍스트 (순수 Canvas API) */
     ctx: CanvasRenderingContext2D;
     /** 현재 hover된 마커 데이터 */
-    hoveredItem: CanvasMarkerData<T> | null;
+    hoveredItem: KonvaCanvasData<T> | null;
     /** 렌더링 유틸리티 함수들 */
     utils: RenderUtils<T>;
     /** 현재 선택된 마커 데이터 배열 (선택 강조용) */
-    selectedItems?: CanvasMarkerData<T>[];
+    selectedItems?: KonvaCanvasData<T>[];
+    /** 외부에서 전달된 단일 선택 아이템 (특별한 효과용) */
+    selectedItem?: KonvaCanvasData<T> | null;
 }
 /**
  * 커스텀 렌더링 함수 타입 - Event Layer

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

@@ -0,0 +1,20 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * 캔버스 데이터 타입 Enum
+ * 마커인지 폴리곤인지 구분하는 상수
+ *
+ * @enum {string}
+ * @memberof WoongCanvasLayer
+ */
+exports.CanvasDataType = void 0;
+
+(function (CanvasDataType) {
+  /** 마커 타입 - 커스텀 렌더링 필요 */
+  CanvasDataType["MARKER"] = "MARKER";
+  /** 폴리곤 타입 - 자동 렌더링 지원 */
+
+  CanvasDataType["POLYGON"] = "POLYGON";
+})(exports.CanvasDataType || (exports.CanvasDataType = {}));