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

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

@@ -0,0 +1,284 @@
+import type React from 'react';
+import type { MarkerOptions, Offset } from '../../../types';
+import type { CanvasData } from '../shared';
+/**
+ * 폴리곤 스타일 정의
+ */
+export interface PolygonStyle {
+    /** 채우기 색상 */
+    fillColor: string;
+    /** 테두리 색상 */
+    strokeColor: string;
+    /** 테두리 두께 */
+    lineWidth: number;
+}
+/**
+ * 폴리곤 스타일 컨텍스트 (선택/호버/활성 상태 정보)
+ */
+export interface PolygonStyleContext {
+    /** 선택 여부 */
+    isSelected: boolean;
+    /** 호버 여부 */
+    isHovered: boolean;
+    /** 활성 여부 (마지막 선택된 항목) */
+    isActive: boolean;
+}
+/**
+ * 폴리곤 스타일 객체
+ *
+ * 상태별 스타일을 정의합니다. 개별 props 방식과 동일한 알고리즘으로 적용됩니다.
+ *
+ * @example
+ * ```typescript
+ * renderStyle={{
+ *   base: { fillColor: 'gray', strokeColor: 'black', lineWidth: 2 },
+ *   selected: { fillColor: 'green', strokeColor: 'darkgreen', lineWidth: 4 },
+ *   active: { fillColor: 'yellow', strokeColor: 'orange', lineWidth: 5 },
+ *   hovered: { fillColor: 'blue', strokeColor: 'darkblue', lineWidth: 3 }
+ * }}
+ * ```
+ */
+export interface PolygonStyleObject {
+    /** 기본 폴리곤 스타일 (필수) */
+    base: PolygonStyle;
+    /** 선택된 폴리곤 스타일 */
+    selected?: PolygonStyle;
+    /** 활성 폴리곤 스타일 (마지막 선택된 항목) */
+    active?: PolygonStyle;
+    /** 호버된 폴리곤 스타일 */
+    hovered?: PolygonStyle;
+}
+/**
+ * 폴리곤 스타일 커스터마이징 함수 타입
+ *
+ * item 데이터와 상태 정보를 기반으로 자유롭게 스타일을 커스터마이징할 수 있습니다.
+ * 스타일을 반환하지 않거나 null/undefined를 반환하면 해당 폴리곤을 그리지 않습니다.
+ *
+ * @param item 폴리곤 데이터
+ * @param context 선택/호버/활성 상태 정보
+ * @returns 커스터마이징된 폴리곤 스타일 (반환하지 않거나 null/undefined면 그리지 않음)
+ */
+export declare type PolygonStyleCustomizer<T> = (item: CanvasData<T>, context: PolygonStyleContext) => PolygonStyle | null | undefined;
+/**
+ * 폴리곤 스타일 커스터마이징 객체 타입
+ *
+ * @example
+ * ```typescript
+ * // 예시 1: deps 있음 (외부 상태를 참조하는 경우)
+ * <CanvasPolygonLayer
+ *   customStyle={{
+ *     callback: (item, context) => {
+ *   	// 상태 정보를 기반으로 스타일 결정
+ *   	if (context.isActive) {
+ *    		return { fillColor: 'yellow', strokeColor: 'orange', lineWidth: 5 };
+ *   	}
+ *   	if (context.isHovered) {
+ *    		return { fillColor: 'blue', strokeColor: 'darkblue', lineWidth: 3 };
+ *   	}
+ *   	if (context.isSelected) {
+ *    		return { fillColor: 'green', strokeColor: 'darkgreen', lineWidth: 4 };
+ *   	}
+ *       return null;
+ *     },
+ *     deps: [selectedPolygon]  // 외부 상태 변경 시 자동 재렌더링
+ *   }}
+ * />
+ *
+ * // 예시 2: deps 없음 (외부 상태를 참조하지 않는 경우)
+ * <CanvasPolygonLayer
+ *   customStyle={{
+ *     callback: (item, context) => {
+ *       if (item.area > 1000) {
+ *         return { fillColor: 'red', strokeColor: 'darkred', lineWidth: 2 };
+ *       }
+ *       return null;
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+export interface PolygonStyleCustomizerWithDeps<T> {
+    /** 스타일 커스터마이징 콜백 함수 (필수) */
+    callback: PolygonStyleCustomizer<T>;
+    /** 외부 상태 의존성 배열 (선택, 변경 시 Canvas 재렌더링) */
+    deps?: React.DependencyList;
+}
+/**
+ * 공통 Props (모든 방식 공통)
+ */
+export interface CanvasPolygonLayerBaseProps<T> extends Pick<MarkerOptions, 'zIndex' | 'anchor' | 'visible'> {
+    /** 렌더링할 폴리곤 데이터 배열 */
+    data: CanvasData<T>[];
+    /** 폴리곤 클릭 시 호출되는 콜백 함수 */
+    onClick?: (payload: CanvasData<T>, selectedIds: Set<string>) => void;
+    /** 다중 선택 활성화 여부 (기본값: false) */
+    enableMultiSelect?: boolean;
+    /** 뷰포트 컬링 여유 공간 (픽셀 단위, 기본값: 100) */
+    cullingMargin?: number;
+    /** Queue 캐시 최대 크기 (기본값: 30000) */
+    maxCacheSize?: number;
+    /** 외부에서 제어하는 선택된 항목 배열 */
+    selectedItems?: CanvasData<T>[];
+    /** 외부에서 전달된 단일 선택 아이템 */
+    selectedItem?: CanvasData<T> | null;
+    /** 상호작용 비활성화 여부 (기본값: false) */
+    disableInteraction?: boolean;
+    /** 최적화 데이터 콜백 (디버깅/모니터링용) */
+    onOptimizationDataUpdate?: (data: {
+        cacheSize: number;
+        cacheEntries: Array<[string, number[][][][] | Offset]>;
+        spatialGridCells: Map<string, CanvasData<T>[]>;
+    }) => void;
+}
+/**
+ * 개별 Props 방식 (기존 방식)
+ *
+ * baseFillColor, baseStrokeColor, baseLineWidth가 있으면 자동으로 개별 props 방식으로 인식됩니다.
+ */
+export interface CanvasPolygonLayerPropsWithIndividualStyles<T> extends CanvasPolygonLayerBaseProps<T> {
+    /** 기본 폴리곤 채우기 색상 (필수) */
+    baseFillColor: string;
+    /** 기본 폴리곤 테두리 색상 (필수) */
+    baseStrokeColor: string;
+    /** 기본 폴리곤 테두리 두께 (필수) */
+    baseLineWidth: number;
+    /** 선택된 폴리곤 채우기 색상 */
+    selectedFillColor?: string;
+    /** 선택된 폴리곤 테두리 색상 */
+    selectedStrokeColor?: string;
+    /** 선택된 폴리곤 테두리 두께 */
+    selectedLineWidth?: number;
+    /** 마지막 선택된 폴리곤(Active) 채우기 색상 */
+    activeFillColor?: string;
+    /** 마지막 선택된 폴리곤(Active) 테두리 색상 */
+    activeStrokeColor?: string;
+    /** 마지막 선택된 폴리곤(Active) 테두리 두께 */
+    activeLineWidth?: number;
+    /** Hover 시 폴리곤 채우기 색상 */
+    hoveredFillColor?: string;
+    /** Hover 시 폴리곤 테두리 색상 */
+    hoveredStrokeColor?: string;
+    /** Hover 시 폴리곤 테두리 두께 */
+    hoveredLineWidth?: number;
+    /** 다른 방식 props는 사용 불가 */
+    renderStyle?: never;
+    /**
+     * 폴리곤 스타일 커스터마이징 객체 (선택)
+     *
+     * customStyle이 제공되면 우선적으로 사용되며, null/undefined를 반환하면 개별 props로 정의된 기본 스타일을 사용합니다.
+     * item 데이터와 상태 정보를 기반으로 자유롭게 스타일을 커스터마이징할 수 있습니다.
+     */
+    customStyle?: PolygonStyleCustomizerWithDeps<T>;
+}
+/**
+ * 객체 Props 방식
+ *
+ * renderStyle 객체가 있으면 자동으로 객체 방식으로 인식됩니다.
+ * 상태별 스타일을 정의하면 개별 props 방식과 동일한 알고리즘으로 적용됩니다.
+ *
+ * @example
+ * ```typescript
+ * renderStyle={{
+ *   base: { fillColor: 'gray', strokeColor: 'black', lineWidth: 2 },
+ *   selected: { fillColor: 'green', strokeColor: 'darkgreen', lineWidth: 4 },
+ *   active: { fillColor: 'yellow', strokeColor: 'orange', lineWidth: 5 },
+ *   hovered: { fillColor: 'blue', strokeColor: 'darkblue', lineWidth: 3 }
+ * }}
+ * ```
+ */
+export interface CanvasPolygonLayerPropsWithObjectStyle<T> extends CanvasPolygonLayerBaseProps<T> {
+    /**
+     * 폴리곤 스타일 객체
+     *
+     * 상태별 스타일을 정의합니다. 개별 props 방식과 동일한 알고리즘으로 적용됩니다.
+     */
+    renderStyle: PolygonStyleObject;
+    /** 다른 방식 props는 사용 불가 */
+    activeFillColor?: never;
+    activeLineWidth?: never;
+    activeStrokeColor?: never;
+    baseFillColor?: never;
+    baseLineWidth?: never;
+    baseStrokeColor?: never;
+    hoveredFillColor?: never;
+    hoveredLineWidth?: never;
+    hoveredStrokeColor?: never;
+    selectedFillColor?: never;
+    selectedLineWidth?: never;
+    selectedStrokeColor?: never;
+    /**
+     * 폴리곤 스타일 커스터마이징 객체 (선택)
+     *
+     * customStyle이 제공되면 우선적으로 사용되며, null/undefined를 반환하면 renderStyle로 정의된 기본 스타일을 사용합니다.
+     * item 데이터와 상태 정보를 기반으로 자유롭게 스타일을 커스터마이징할 수 있습니다.
+     */
+    customStyle?: PolygonStyleCustomizerWithDeps<T>;
+}
+/**
+ * 함수 Props 방식 (커스터마이징 방식)
+ *
+ * customStyle 함수가 있으면 자동으로 함수 방식으로 인식됩니다.
+ * item 데이터와 상태 정보를 기반으로 자유롭게 스타일을 커스터마이징할 수 있습니다.
+ * 스타일을 반환하지 않거나 null/undefined를 반환하면 해당 폴리곤을 그리지 않습니다.
+ *
+ * @example
+ * ```typescript
+ * customStyle={(item, context) => {
+ *   // item의 속성에 따라 동적으로 스타일 결정
+ *   if (item.someProperty > 100) {
+ *     return { fillColor: 'red', strokeColor: 'darkred', lineWidth: 3 };
+ *   }
+ *
+ *   // 상태 정보를 기반으로 스타일 결정
+ *   if (context.isActive) {
+ *     return { fillColor: 'yellow', strokeColor: 'orange', lineWidth: 5 };
+ *   }
+ *   if (context.isHovered) {
+ *     return { fillColor: 'blue', strokeColor: 'darkblue', lineWidth: 3 };
+ *   }
+ *   if (context.isSelected) {
+ *     return { fillColor: 'green', strokeColor: 'darkgreen', lineWidth: 4 };
+ *   }
+ *
+ *   // 아무것도 반환하지 않으면 그리지 않음 (return null 또는 return undefined도 가능)
+ * }}
+ * ```
+ */
+export interface CanvasPolygonLayerPropsWithCustomStyle<T> extends CanvasPolygonLayerBaseProps<T> {
+    /**
+     * 폴리곤 스타일 커스터마이징 객체
+     *
+     * item 데이터와 상태 정보를 기반으로 자유롭게 스타일을 커스터마이징할 수 있습니다.
+     * 스타일을 반환하지 않거나 null/undefined를 반환하면 해당 폴리곤을 그리지 않습니다.
+     */
+    customStyle: PolygonStyleCustomizerWithDeps<T>;
+    /** 다른 방식 props는 사용 불가 */
+    activeFillColor?: never;
+    activeLineWidth?: never;
+    activeStrokeColor?: never;
+    baseFillColor?: never;
+    baseLineWidth?: never;
+    baseStrokeColor?: never;
+    hoveredFillColor?: never;
+    hoveredLineWidth?: never;
+    hoveredStrokeColor?: never;
+    renderStyle?: never;
+    selectedFillColor?: never;
+    selectedLineWidth?: never;
+    selectedStrokeColor?: never;
+}
+/**
+ * CanvasPolygonLayer Props (Discriminated Union)
+ *
+ * 세 가지 스타일 지정 방식을 지원:
+ * 1. 개별 props 방식: baseFillColor, baseStrokeColor, baseLineWidth가 있으면 자동으로 개별 props 방식
+ * 2. 객체 방식: renderStyle 객체가 있으면 자동으로 객체 방식
+ * 3. 함수 방식: customStyle 함수가 있으면 자동으로 함수 방식
+ *
+ * customStyle은 개별 props 방식 또는 renderStyle 객체 방식과 함께 사용할 수 있습니다.
+ * customStyle이 제공되면 우선적으로 사용되며, null/undefined를 반환하면 기본 스타일을 사용합니다.
+ * styleMode prop은 필요 없으며, 각 prop의 존재 여부로 자동 판단됩니다.
+ *
+ * @template T 폴리곤 데이터의 추가 속성 타입
+ */
+export declare type CanvasPolygonLayerProps<T> = CanvasPolygonLayerPropsWithIndividualStyles<T> | CanvasPolygonLayerPropsWithObjectStyle<T> | CanvasPolygonLayerPropsWithCustomStyle<T>;

package/dist/components/mint-map/core/advanced/canvas/CanvasMarker.d.ts

@@ -1,5 +1,12 @@
 import React from "react";
 import { MarkerOptions, Offset, Position } from "../../../types";
+/**
+ * 2026-01-06 장한별
+ * 고주영팀장님이 만든 캔버스 마커
+ * 클릭, hover 등의 이벤트가 구현되어있지 않는 버전
+ * RA 지도 제품에서 CanvasMarker 컴포넌트를 사용하고 있음
+ *
+ */
 export interface CanvasMarkerRendererParams<T> {
     context: CanvasRenderingContext2D;
     offset: Offset[];

package/dist/components/mint-map/core/advanced/canvas/CanvasMarkerClaude.js

@@ -107,12 +107,12 @@ var CanvasMarkerClaude = React__default["default"].memo(function CanvasMarkerCla
   var hoveredPolygonRef = React.useRef(null);
   var clickedPolygonRef = React.useRef(null);
   var hoveredMarkerRef = React.useRef(null);
-  var clickedMarkerRef = React.useRef(null); // 🚀 WoongCanvasMarker 방식: 단순한 data ref (geohash 제거)
+  var clickedMarkerRef = React.useRef(null); // 🚀 CanvasMarker 방식: 단순한 data ref (geohash 제거)
 
   var polygonsRef = React.useRef([]);
   var markersRef = React.useRef([]); // 마커 경계 정보 저장 (hit-test용)
 
-  var markerBoundsRef = React.useRef(new Map()); // 🚀 드래그 추적용 (WoongCanvasMarker 방식)
+  var markerBoundsRef = React.useRef(new Map()); // 🚀 드래그 추적용 (CanvasMarker 방식)
 
   var draggingRef = React.useRef(false);
   var prevCenterOffsetRef = React.useRef(null);
@@ -172,7 +172,7 @@ var CanvasMarkerClaude = React__default["default"].memo(function CanvasMarkerCla
     if (!baseContextRef.current || !polygonsRef.current || polygonsRef.current.length === 0) return;
     canvasUtil.clearRect(baseCanvasRef.current, baseContextRef.current);
     var cacheMissCount = 0; // 캐시 미스 카운트
-    // 🚀 WoongCanvasMarker 방식: 전체 데이터 순회 (필터링 제거)
+    // 🚀 CanvasMarker 방식: 전체 데이터 순회 (필터링 제거)
 
     polygonsRef.current.forEach(function (polygon) {
       if (polygon.visible === false) return; // 🚀 캐시 확인 (ID 기반으로 변경)
@@ -243,7 +243,7 @@ var CanvasMarkerClaude = React__default["default"].memo(function CanvasMarkerCla
     if (!markersRef.current || markersRef.current.length === 0) return;
     canvasUtil.clearRect(baseMarkerCanvasRef.current, baseMarkerContextRef.current); // 마커 경계 정보 초기화
 
-    markerBoundsRef.current.clear(); // 🚀 WoongCanvasMarker 방식: 전체 데이터 순회 (필터링 제거)
+    markerBoundsRef.current.clear(); // 🚀 CanvasMarker 방식: 전체 데이터 순회 (필터링 제거)
 
     markersRef.current.forEach(function (marker) {
       var _a, _b;
@@ -566,7 +566,7 @@ var CanvasMarkerClaude = React__default["default"].memo(function CanvasMarkerCla
     }
 
     return null;
-  }; // IDLE 이벤트 핸들러 (WoongCanvasMarker 최적화 적용)
+  }; // IDLE 이벤트 핸들러 (CanvasMarker 최적화 적용)
 
 
   var handleIdle = function () {
@@ -632,7 +632,7 @@ var CanvasMarkerClaude = React__default["default"].memo(function CanvasMarkerCla
       x: event.clientX - rect.left,
       y: event.clientY - rect.top
     };
-  }; // 🚀 지도 클릭 이벤트 핸들러 (WoongCanvasMarker 방식 - controller.addEventListener)
+  }; // 🚀 지도 클릭 이벤트 핸들러 (CanvasMarker 방식 - controller.addEventListener)
 
 
   var handleMapClick = function (event) {
@@ -724,7 +724,7 @@ var CanvasMarkerClaude = React__default["default"].memo(function CanvasMarkerCla
   var rafIdRef = React.useRef(); // 마우스 이벤트 핸들러 (requestAnimationFrame으로 최적화)
 
   var handleMouseMove = function (e) {
-    // 🚀 드래그 중이면 호버 처리 스킵 (WoongCanvasMarker 방식)
+    // 🚀 드래그 중이면 호버 처리 스킵 (CanvasMarker 방식)
     if (draggingRef.current) return; // 이미 RAF가 대기 중이면 스킵
 
     if (rafIdRef.current) return;

package/dist/components/mint-map/core/advanced/canvas/index.d.ts

@@ -1,3 +1,2 @@
 export * from './CanvasMarker';
-export * from './CanvasMarkerHanquf';
 export * from './CanvasMarkerClaude';

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

@@ -1,5 +1,7 @@
-export * from './shapes';
 export * from './canvas';
+export * from './CanvasMarkerLayer';
+export * from './CanvasPolygonLayer';
 export * from './MapBuildingProjection';
 export * from './MapLoadingComponents';
-export * from './woongCanvas';
+export * from './shapes';
+export * from './shared';

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

@@ -0,0 +1,44 @@
+import React from 'react';
+import { QueueCache } from './performance';
+import { CanvasData } from './types';
+import { Offset } from '../../../types';
+/**
+ * Canvas 컴포넌트 인스턴스 인터페이스
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ */
+export interface ComponentInstance<T> {
+    zIndex: number;
+    hitTest: (offset: Offset) => boolean;
+    onClick?: (payload: CanvasData<T>, selectedIds: Set<string>) => void;
+    onMouseOver?: (payload: CanvasData<T>) => void;
+    onMouseOut?: (payload: CanvasData<T>) => void;
+    findData: (offset: Offset) => CanvasData<T> | null;
+    setHovered: (data: CanvasData<T> | null) => void;
+    handleLocalClick: (data: CanvasData<T>) => void;
+    getSelectedIds: () => Set<string>;
+    isInteractionDisabled: () => boolean;
+}
+interface CanvasContextValue {
+    registerComponent: <T>(instance: ComponentInstance<T>) => void;
+    unregisterComponent: <T>(instance: ComponentInstance<T>) => void;
+    sharedMarkerCache: QueueCache<string, Offset>;
+    sharedPolygonCache: QueueCache<string, number[][][][]>;
+}
+/**
+ * CanvasProvider 컴포넌트
+ *
+ * 다중 Canvas 인스턴스를 관리하고 zIndex 기반 이벤트 우선순위를 처리합니다.
+ */
+export declare const CanvasProvider: React.FC<{
+    children: React.ReactNode;
+    markerMaxCacheSize?: number;
+    polygonMaxCacheSize?: number;
+}>;
+/**
+ * Canvas Context Hook
+ *
+ * @returns CanvasContextValue 또는 null (Provider 없으면)
+ */
+export declare const useCanvasContext: () => CanvasContextValue | null;
+export {};

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

@@ -0,0 +1,230 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+var performance = require('./performance.js');
+var MintMapProvider = require('../../provider/MintMapProvider.js');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
+
+var CanvasContext = React.createContext(null);
+/**
+ * CanvasProvider 컴포넌트
+ *
+ * 다중 Canvas 인스턴스를 관리하고 zIndex 기반 이벤트 우선순위를 처리합니다.
+ */
+
+/* eslint-disable no-restricted-syntax */
+
+/* eslint-disable no-continue */
+
+var CanvasProvider = function (_a) {
+  var children = _a.children,
+      _b = _a.markerMaxCacheSize,
+      markerMaxCacheSize = _b === void 0 ? 5000 : _b,
+      _c = _a.polygonMaxCacheSize,
+      polygonMaxCacheSize = _c === void 0 ? 30000 : _c;
+  var controller = MintMapProvider.useMintMapController(); // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+  var componentsRef = React.useRef([]); // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+  var currentHoveredRef = React.useRef(null); // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+  var currentHoveredDataRef = React.useRef(null);
+  var draggingRef = React.useRef(false); // 공유 캐시 (모든 레이어가 공유)
+
+  var sharedMarkerCacheRef = React.useRef(new performance.QueueCache(markerMaxCacheSize));
+  var sharedPolygonCacheRef = React.useRef(new performance.QueueCache(polygonMaxCacheSize)); // 컴포넌트 등록 (zIndex 내림차순 정렬)
+
+  var registerComponent = React.useCallback(function (instance) {
+    componentsRef.current.push(instance);
+    componentsRef.current.sort(function (a, b) {
+      return b.zIndex - a.zIndex;
+    });
+  }, []); // 컴포넌트 등록 해제
+
+  var unregisterComponent = React.useCallback(function (instance) {
+    if (currentHoveredRef.current === instance) {
+      currentHoveredRef.current = null;
+      currentHoveredDataRef.current = null;
+    }
+
+    componentsRef.current = componentsRef.current.filter(function (c) {
+      return c !== instance;
+    });
+  }, []); // 전역 클릭 핸들러 (zIndex 우선순위)
+
+  var handleGlobalClick = React.useCallback(function (event) {
+    var _a, _b;
+
+    try {
+      if (!((_a = event === null || event === void 0 ? void 0 : event.param) === null || _a === void 0 ? void 0 : _a.position)) return;
+      var clickedOffset = void 0;
+
+      try {
+        clickedOffset = controller.positionToOffset(event.param.position);
+      } catch (error) {
+        // positionToOffset 실패 시 조용히 종료 (기존 동작 보장)
+        console.warn('[CanvasProvider] positionToOffset failed:', error);
+        return;
+      } // zIndex 내림차순으로 정렬된 컴포넌트 순회 (높은 zIndex가 먼저 처리)
+
+
+      for (var _i = 0, _c = componentsRef.current; _i < _c.length; _i++) {
+        var component = _c[_i];
+
+        try {
+          if (component.isInteractionDisabled()) continue;
+          var data = component.findData(clickedOffset);
+          if (!data) continue; // 첫 번째로 찾은 항목만 처리하고 종료 (zIndex 우선순위)
+
+          component.handleLocalClick(data);
+          (_b = component.onClick) === null || _b === void 0 ? void 0 : _b.call(component, data, component.getSelectedIds());
+          return;
+        } catch (error) {
+          // 개별 컴포넌트 처리 중 에러 발생 시 다음 컴포넌트로 계속 진행
+          console.warn('[CanvasProvider] Component click handler error:', error);
+          continue;
+        }
+      }
+    } catch (error) {
+      // 전체 핸들러 에러 시 조용히 종료 (앱 크래시 방지)
+      console.error('[CanvasProvider] handleGlobalClick error:', error);
+    }
+  }, [controller]); // 전역 마우스 이동 핸들러 (zIndex 우선순위)
+
+  var handleGlobalMouseMove = React.useCallback(function (event) {
+    var _a;
+
+    try {
+      if (draggingRef.current || !((_a = event === null || event === void 0 ? void 0 : event.param) === null || _a === void 0 ? void 0 : _a.position)) return;
+      var mouseOffset = void 0;
+
+      try {
+        mouseOffset = controller.positionToOffset(event.param.position);
+      } catch (error) {
+        // positionToOffset 실패 시 조용히 종료 (기존 동작 보장)
+        console.warn('[CanvasProvider] positionToOffset failed:', error);
+        return;
+      } // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+
+      var newHoveredComponent = null; // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+      var newHoveredData = null; // zIndex 내림차순으로 정렬된 컴포넌트 순회 (높은 zIndex가 먼저 처리)
+
+      for (var _i = 0, _b = componentsRef.current; _i < _b.length; _i++) {
+        var component = _b[_i];
+
+        try {
+          if (component.isInteractionDisabled()) continue;
+          var data = component.findData(mouseOffset);
+          if (!data) continue; // 첫 번째로 찾은 항목만 hover 처리 (zIndex 우선순위)
+
+          newHoveredComponent = component;
+          newHoveredData = data;
+          break;
+        } catch (error) {
+          // 개별 컴포넌트 처리 중 에러 발생 시 다음 컴포넌트로 계속 진행
+          console.warn('[CanvasProvider] Component mouse move handler error:', error);
+          continue;
+        }
+      } // hover 상태가 변경되지 않았으면 종료 (불필요한 렌더링 방지)
+
+
+      if (currentHoveredRef.current === newHoveredComponent && currentHoveredDataRef.current === newHoveredData) {
+        return;
+      } // 기존 hover 항목에 mouseOut 이벤트 발생
+
+
+      if (currentHoveredRef.current) {
+        try {
+          currentHoveredRef.current.setHovered(null);
+
+          if (currentHoveredRef.current.onMouseOut && currentHoveredDataRef.current) {
+            currentHoveredRef.current.onMouseOut(currentHoveredDataRef.current);
+          }
+        } catch (error) {
+          // mouseOut 이벤트 에러 시 조용히 처리 (기존 동작 보장)
+          console.warn('[CanvasProvider] mouseOut handler error:', error);
+        }
+      } // 새 hover 항목에 mouseOver 이벤트 발생
+
+
+      if (newHoveredComponent && newHoveredData) {
+        try {
+          newHoveredComponent.setHovered(newHoveredData);
+
+          if (newHoveredComponent.onMouseOver) {
+            newHoveredComponent.onMouseOver(newHoveredData);
+          }
+        } catch (error) {
+          // mouseOver 이벤트 에러 시 조용히 처리 (기존 동작 보장)
+          console.warn('[CanvasProvider] mouseOver handler error:', error);
+        }
+      }
+
+      currentHoveredRef.current = newHoveredComponent;
+      currentHoveredDataRef.current = newHoveredData;
+    } catch (error) {
+      // 전체 핸들러 에러 시 조용히 종료 (앱 크래시 방지)
+      console.error('[CanvasProvider] handleGlobalMouseMove error:', error);
+    }
+  }, [controller]);
+  var handleZoomStart = React.useCallback(function () {
+    draggingRef.current = true;
+  }, []);
+  var handleIdle = React.useCallback(function () {
+    draggingRef.current = false;
+  }, []);
+  React.useEffect(function () {
+    try {
+      controller.addEventListener('CLICK', handleGlobalClick);
+      controller.addEventListener('MOUSEMOVE', handleGlobalMouseMove);
+      controller.addEventListener('ZOOMSTART', handleZoomStart);
+      controller.addEventListener('IDLE', handleIdle);
+    } catch (error) {
+      // 이벤트 리스너 등록 실패 시 경고만 출력 (기존 동작 보장)
+      console.warn('[CanvasProvider] Failed to add event listeners:', error);
+    }
+
+    return function () {
+      try {
+        controller.removeEventListener('CLICK', handleGlobalClick);
+        controller.removeEventListener('MOUSEMOVE', handleGlobalMouseMove);
+        controller.removeEventListener('ZOOMSTART', handleZoomStart);
+        controller.removeEventListener('IDLE', handleIdle);
+      } catch (error) {
+        // cleanup 중 에러 발생 시 조용히 처리 (controller가 이미 destroy된 경우 등)
+        // 에러를 무시해도 메모리 누수는 발생하지 않음 (이벤트 리스너는 자동으로 정리됨)
+        console.warn('[CanvasProvider] Failed to remove event listeners:', error);
+      }
+    };
+  }, [controller, handleGlobalClick, handleGlobalMouseMove, handleZoomStart, handleIdle]);
+  var contextValue = React.useMemo(function () {
+    return {
+      registerComponent: registerComponent,
+      sharedMarkerCache: sharedMarkerCacheRef.current,
+      sharedPolygonCache: sharedPolygonCacheRef.current,
+      unregisterComponent: unregisterComponent
+    };
+  }, [registerComponent, unregisterComponent]);
+  return React__default["default"].createElement(CanvasContext.Provider, {
+    value: contextValue
+  }, children);
+};
+/**
+ * Canvas Context Hook
+ *
+ * @returns CanvasContextValue 또는 null (Provider 없으면)
+ */
+
+var useCanvasContext = function () {
+  return React.useContext(CanvasContext);
+};
+
+exports.CanvasProvider = CanvasProvider;
+exports.useCanvasContext = useCanvasContext;

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

@@ -0,0 +1,20 @@
+import type { Offset } from '../../../types';
+import { EventParam, MapUIEventParam } from '../../../types';
+import type { MintMapController } from '../../MintMapController';
+/**
+ * 이벤트 유효성 검증 및 좌표 변환
+ *
+ * @param event 이벤트 파라미터
+ * @param context CanvasContext 인스턴스
+ * @param controller MintMapController 인스턴스
+ * @returns 유효한 화면 좌표 또는 null
+ */
+export declare const validateEvent: (event: EventParam<MapUIEventParam> | null | undefined, context: any, controller: MintMapController) => Offset | null;
+/**
+ * Map의 values를 배열로 변환
+ *
+ * @template T Map 값의 타입
+ * @param map 변환할 Map
+ * @returns Map의 값 배열
+ */
+export declare const mapValuesToArray: <T>(map: Map<string, T>) => T[];