@mint-ui/map 1.2.0-test.65 → 1.2.0-test.66

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

@@ -0,0 +1,280 @@
+import type React from 'react';
+import type { MarkerOptions } 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;
+    /** 뷰포트 컬링 활성화 여부 (기본값: false) */
+    enableViewportCulling?: boolean;
+    /** 뷰포트 컬링 여유 공간 (픽셀 단위, 기본값: 100) */
+    cullingMargin?: number;
+    /** LRU 캐시 최대 크기 (기본값: 10000) */
+    maxCacheSize?: number;
+    /** 외부에서 제어하는 선택된 항목 배열 */
+    selectedItems?: CanvasData<T>[];
+    /** 외부에서 전달된 단일 선택 아이템 */
+    selectedItem?: CanvasData<T> | null;
+    /** 상호작용 비활성화 여부 (기본값: false) */
+    disableInteraction?: boolean;
+}
+/**
+ * 개별 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>;