vanta-react/dist/index.d.ts

React components for Vanta.js animated backgrounds with TypeScript support - CDN optimized with automatic library loading

import { Component } from 'react';
import { default as default_2 } from 'react';
import { ErrorInfo } from 'react';
import { ReactNode } from 'react';

/**
 * 라이브러리가 준비되었는지 확인하는 함수
 * @returns 모든 라이브러리가 로드되고 전역에서 사용 가능한지 여부
 */
export declare const areLibrariesReady: () => boolean;

/**
 * 효과 캐시를 초기화하는 함수
 * 메모리 정리나 테스트 목적으로 사용됩니다.
 */
export declare const clearEffectCache: () => void;

/**
 * 로드된 Vanta 이펙트 캐시를 클리어
 */
export declare const clearVantaCache: () => void;

/**
 * Vanta 컴포넌트를 위한 에러 바운더리
 * React 16+ 호환성을 보장하며, Vanta 효과 관련 오류를 안전하게 처리합니다.
 * React 19에서 테스트되고 최적화되었습니다.
 */
export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
    private retryTimeoutId;
    constructor(props: ErrorBoundaryProps);
    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
    componentWillUnmount(): void;
    handleRetry: () => void;
    handleRetryWithDelay: () => void;
    render(): ReactNode;
}

declare interface ErrorBoundaryProps {
    children: ReactNode;
    fallback?: ReactNode;
    onError?: (error: Error, errorInfo: ErrorInfo) => void;
}

declare interface ErrorBoundaryState {
    hasError: boolean;
    error: Error | null;
    errorInfo: ErrorInfo | null;
}

/**
 * 성능 모니터링을 완료하는 함수
 */
export declare const finishPerformanceMonitoring: (metrics: PerformanceMetrics, effectsLoaded: number, success: boolean, errorMessage?: string) => PerformanceMetrics;

/**
 * 사용 가능한 효과 목록을 반환하는 함수
 * CDN에서 지원하는 모든 Vanta 효과들을 나열합니다.
 */
export declare const getAvailableEffects: () => string[];

/**
 * 현재 캐시된 효과들의 목록을 반환하는 함수
 * 이미 로드되어 즉시 사용 가능한 효과들을 확인할 수 있습니다.
 */
export declare const getCachedEffects: () => string[];

/**
 * CDN 라이브러리 로드 상태 확인
 */
export declare const getCdnLibraryStatus: () => {
    threeLoaded: boolean;
    p5Loaded: boolean;
    vantaLoaded: boolean;
    threeAvailable: boolean;
    p5Available: boolean;
    vantaAvailable: boolean;
};

/**
 * 메모리 사용량을 측정하는 함수
 */
export declare const getMemoryUsage: () => number;

export declare const getPreloadedP5: () => any;

/**
 * 전역 객체에서 라이브러리를 안전하게 가져오는 함수들
 */
export declare const getPreloadedThree: () => any;

/**
 * 라이브러리 로드 상태 정보를 반환하는 함수
 */
export declare const getPreloadStatus: () => {
    isPreloaded: boolean;
    isLoading: boolean;
    hasError: boolean;
    error: string | null;
    threeAvailable: boolean;
    p5Available: boolean;
    loadSource: "CDN";
};

/**
 * CDN URL을 반환하는 헬퍼 함수
 * @param effectName 이펙트 이름
 * @returns CDN URL
 */
export declare const getVantaEffectCdnUrl: (effectName: VantaEffectName) => string;

/**
 * Vanta 이펙트 로드 상태 확인
 */
export declare const getVantaLoadStatus: () => {
    loadedEffects: string[];
    loadingEffects: string[];
    vantaAvailable: boolean;
    loadedCount: number;
    loadingCount: number;
};

/**
 * 성능 모니터링이 활성화되어 있는지 확인하는 함수
 */
export declare const isPerformanceMonitoringEnabled: () => boolean;

/**
 * Vanta 이펙트가 사용 가능한지 확인
 * @param effectName 확인할 이펙트 이름
 * @returns 이펙트 사용 가능 여부
 */
export declare const isVantaEffectAvailable: (effectName: VantaEffectName) => boolean;

/**
 * 필요한 라이브러리들을 병렬로 CDN에서 로드
 */
export declare const loadCdnLibraries: (needsP5?: boolean) => Promise<{
    p5?: any;
    THREE: any;
}>;

/**
 * p5.js를 CDN에서 로드
 */
export declare const loadCdnP5: () => Promise<any>;

/**
 * Three.js를 CDN에서 로드
 */
export declare const loadCdnThree: () => Promise<any>;

/**
 * Vanta 특정 이펙트를 CDN에서 로드
 */
export declare const loadCdnVantaEffect: (effectName: string) => Promise<any>;

/**
 * 여러 Vanta 이펙트를 병렬로 로드
 * @param effectNames 로드할 이펙트 이름 배열
 * @returns 로드된 이펙트들의 객체
 */
export declare const loadMultipleVantaEffects: (effectNames: VantaEffectName[]) => Promise<Record<string, any>>;

/**
 * CDN에서 Vanta 효과를 동적으로 로드하는 함수
 * 이미 로드된 효과는 캐시에서 반환하여 성능을 최적화합니다.
 * 동시에 같은 효과를 로드하려는 경우 중복 로딩을 방지합니다.
 */
export declare const loadVantaEffect: (effectName: string) => Promise<VantaCreator | null>;

/**
 * CDN에서 Vanta 이펙트를 로드하는 함수
 * @param effectName 로드할 이펙트 이름
 * @returns 로드된 이펙트 생성자
 */
export declare const loadVantaEffectFromCdn: (effectName: VantaEffectName) => Promise<any>;

/**
 * 진행률을 로깅하는 함수
 */
export declare const logProgress: (loaded: number, total: number) => void;

/**
 * 성능 모니터링을 위한 유틸리티 함수들
 * 개발 모드에서만 활성화되며, preloading 성능 추적을 지원합니다.
 */
export declare interface PerformanceMetrics {
    /** 로딩 시작 시간 (milliseconds) */
    startTime: number;
    /** 로딩 완료 시간 (milliseconds) */
    endTime?: number;
    /** 총 로딩 시간 (milliseconds) */
    loadTime?: number;
    /** 로딩 시작 전 메모리 사용량 (bytes) */
    memoryBefore?: number;
    /** 로딩 완료 후 메모리 사용량 (bytes) */
    memoryAfter?: number;
    /** 메모리 증가량 (bytes) */
    memoryIncrease?: number;
    /** 로드된 효과 개수 */
    effectsLoaded: number;
    /** 로딩 성공 여부 */
    success: boolean;
    /** 에러 메시지 (실패한 경우) */
    errorMessage?: string;
}

/**
 * 모든 Vanta 이펙트를 미리 로드 (선택사항)
 */
export declare const preloadAllVantaEffects: () => Promise<void>;

/**
 * three.js와 p5.js를 CDN에서 앱 시작 시점에 미리 로드합니다.
 * 중복 호출을 방지하고 Promise 기반 동기화를 제공합니다.
 * React 19 호환성을 위해 개선되었습니다.
 */
export declare const preloadLibraries: () => Promise<void>;

/**
 * 인기 있는 Vanta 이펙트들을 미리 로드
 */
export declare const preloadPopularVantaEffects: () => Promise<void>;

/**
 * 프리로드 상태를 초기화하는 함수 (테스트나 재시작 용도)
 */
export declare const resetPreloadState: () => void;

/**
 * 성능 모니터링을 시작하는 함수
 */
export declare const startPerformanceMonitoring: () => PerformanceMetrics;

/**
 * Vanta 효과 로딩 상태를 관리하는 커스텀 훅
 */
export declare const useVantaEffect: (effectName: VantaEffectName_2) => {
    isLoading: boolean;
    error: string | null;
    isLoaded: boolean;
};

/**
 * Vanta.js 효과를 React 컴포넌트로 래핑한 컴포넌트입니다.
 * 동적으로 Vanta 효과 모듈을 로드하고, React 라이프사이클에 맞게 관리합니다.
 */
export declare const Vanta: default_2.FC<VantaProps>;

/**
 * 사용 가능한 Vanta 이펙트 목록
 */
export declare const VANTA_EFFECTS: readonly ["birds", "cells", "clouds", "clouds2", "dots", "fog", "globe", "halo", "net", "rings", "ripple", "topology", "trunk", "waves"];

/**
 * Vanta 효과를 생성하는 함수의 시그니처를 정의합니다.
 * 이 함수는 el(DOM 요소), THREE 라이브러리 등 여러 옵션을 포함하는 객체를 인자로 받습니다.
 */
export declare type VantaCreator = (options: {
    el: HTMLElement;
    THREE: any;
    [key: string]: any;
}) => VantaEffect;

/**
 * Vanta.js 효과 인스턴스의 타입을 정의하는 인터페이스입니다.
 * Vanta 인스턴스는 다양한 내부 속성을 가지지만, 외부에서 제어할 때 가장 중요한 것은
 * 메모리 해제를 위한 destroy 메서드와 크기 조정을 위한 resize 메서드입니다.
 */
export declare interface VantaEffect {
    destroy: () => void;
    resize?: () => void;
    [key: string]: any;
}

export declare type VantaEffectName = typeof VANTA_EFFECTS[number];

/**
 * Vanta.js가 제공하는 효과 이름들을 TypeScript의 'string literal union' 타입으로 정의합니다.
 * 이를 통해 effect prop에 정해진 문자열만 사용하도록 강제하여 오타를 방지하고,
 * 코드 에디터에서 자동 완성 기능을 활용할 수 있습니다.
 */
declare type VantaEffectName_2 = 'birds' | 'cells' | 'clouds' | 'clouds2' | 'fog' | 'globe' | 'net' | 'rings' | 'halo' | 'ripple' | 'dots' | 'topology' | 'trunk' | 'waves';

/**
 * Vanta 컴포넌트가 받을 props의 타입을 정의하는 인터페이스입니다.
 * 각 prop의 타입과 역할을 명확하게 문서화합니다.
 */
export declare interface VantaProps {
    /** 렌더링할 Vanta 효과의 이름 (e.g., 'net', 'waves') */
    effect: VantaEffectName_2;
    /** Vanta 효과에 전달할 설정 옵션 객체. 키는 문자열, 값은 무엇이든 될 수 있습니다. */
    options?: Record<string, any>;
    /** 컨테이너 div에 추가할 사용자 정의 CSS 클래스 */
    className?: string;
    /** 컨테이너 div에 적용할 인라인 스타일 */
    style?: default_2.CSSProperties;
    /** true로 설정하면 화면 전체를 덮는 배경으로 동작합니다 (fixed positioning, full screen) */
    background?: boolean;
    /** 라이브러리를 자동으로 로드할지 여부 (기본값: true) */
    autoLoad?: boolean;
    /** 라이브러리 로딩 중에 표시할 커스텀 컴포넌트 */
    loadingComponent?: default_2.ReactNode;
    /** 에러 발생 시 표시할 커스텀 컴포넌트 또는 렌더 함수 */
    errorComponent?: default_2.ReactNode | ((error: string, retry: () => void) => default_2.ReactNode);
    /** 로딩 실패 시 재시도 횟수 (기본값: 3) */
    retryCount?: number;
    /** 재시도 간격 (밀리초, 기본값: 1000) */
    retryDelay?: number;
    /** 라이브러리 로딩이 시작될 때 호출되는 콜백 */
    onLoadStart?: () => void;
    /** 라이브러리 로딩이 성공적으로 완료될 때 호출되는 콜백 */
    onLoadSuccess?: () => void;
    /** 라이브러리 로딩 중 에러가 발생할 때 호출되는 콜백 */
    onLoadError?: (error: string) => void;
}

export { }