@hua-labs/motion-core 2.2.2 → 2.2.3

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
-import { CSSProperties, RefObject } from 'react';
+import react__default, { CSSProperties, RefObject } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
  * HUA Motion Core - 의존성 제로 모션 엔진
@@ -35,7 +36,7 @@ interface MotionOptions {
     onComplete?: () => void;
     onCancel?: () => void;
 }
-interface Motion {
+interface Motion$1 {
     id: string;
     element: HTMLElement;
     isRunning: boolean;
@@ -72,7 +73,7 @@ declare class MotionEngine {
     /**
      * 모션 상태 확인
      */
-    getMotion(motionId: string): Motion | undefined;
+    getMotion(motionId: string): Motion$1 | undefined;
     /**
      * 실행 중인 모션 수
      */
@@ -677,9 +678,25 @@ declare function useSmartMotion<T extends HTMLElement = HTMLDivElement>(options?
  * 내부에서 선택된 type에 맞는 로직만 실행 (6개 훅 동시 호출 제거)
  */
 
+interface MotionEffects {
+    fade?: boolean | {
+        targetOpacity?: number;
+    };
+    slide?: boolean | {
+        direction?: 'up' | 'down' | 'left' | 'right';
+        distance?: number;
+    };
+    scale?: boolean | {
+        from?: number;
+        to?: number;
+    };
+    bounce?: boolean;
+}
 interface UseUnifiedMotionOptions extends Omit<BaseMotionOptions, 'autoStart'> {
-    /** Motion type to use */
-    type: EntranceType;
+    /** Motion type to use (single effect mode) */
+    type?: EntranceType;
+    /** Multiple effects to combine (multi-effect mode) */
+    effects?: MotionEffects;
     /** Auto start animation @default true */
     autoStart?: boolean;
     /** Slide distance (px) for slide types @default 50 */
@@ -1044,6 +1061,193 @@ declare function useGestureMotion(options: GestureMotionOptions): {
     isActive: boolean;
 };
 
+interface TypewriterOptions {
+    /** 타이핑할 텍스트 */
+    text: string;
+    /** 글자당 딜레이 (ms) @default 50 */
+    speed?: number;
+    /** 시작 딜레이 (ms) @default 0 */
+    delay?: number;
+    /** 활성화 여부 @default true */
+    enabled?: boolean;
+    /** 완료 콜백 */
+    onComplete?: () => void;
+}
+interface TypewriterReturn {
+    /** 현재 표시 중인 텍스트 */
+    displayText: string;
+    /** 타이핑 진행 중 여부 */
+    isTyping: boolean;
+    /** 진행률 (0-1) */
+    progress: number;
+    /** 타이핑 재시작 */
+    restart: () => void;
+}
+/**
+ * useTypewriter - 타이핑 효과 훅
+ *
+ * @example
+ * ```tsx
+ * const { displayText, isTyping } = useTypewriter({ text: 'Hello, world!' })
+ * return <h1>{displayText}<span className="animate-pulse">|</span></h1>
+ * ```
+ */
+declare function useTypewriter(options: TypewriterOptions): TypewriterReturn;
+
+interface CustomCursorOptions {
+    /** 활성화 여부 @default true */
+    enabled?: boolean;
+    /** 커서 크기 (px) @default 32 */
+    size?: number;
+    /** 스프링 스무딩 (0-1, 낮을수록 부드러움) @default 0.15 */
+    smoothing?: number;
+    /** 호버 시 스케일 @default 1.5 */
+    hoverScale?: number;
+    /** data-cursor 속성 요소 감지 @default true */
+    detectLabels?: boolean;
+}
+interface CustomCursorReturn {
+    /** 커서 x 좌표 (smoothed) */
+    x: number;
+    /** 커서 y 좌표 (smoothed) */
+    y: number;
+    /** 호버 중인 요소의 data-cursor 값 */
+    label: string | null;
+    /** 호버 상태 여부 */
+    isHovering: boolean;
+    /** 커서 스타일 (CSS variables 포함) */
+    style: CSSProperties;
+    /** 커서 가시 여부 */
+    isVisible: boolean;
+}
+/**
+ * useCustomCursor - 커스텀 커서 효과 훅
+ *
+ * 마우스를 따라다니는 커스텀 커서를 구현합니다.
+ * 스프링 보간으로 부드러운 추적, data-cursor 라벨 감지.
+ *
+ * @example
+ * ```tsx
+ * const cursor = useCustomCursor()
+ * return (
+ *   <>
+ *     <div style={cursor.style} className="custom-cursor" />
+ *     <button data-cursor="Click me">Hover me</button>
+ *   </>
+ * )
+ * ```
+ */
+declare function useCustomCursor(options?: CustomCursorOptions): CustomCursorReturn;
+
+interface MagneticCursorOptions {
+    /** 자석 끌림 강도 (0-1) @default 0.3 */
+    strength?: number;
+    /** 자석 작동 반경 (px) @default 100 */
+    radius?: number;
+    /** 활성화 여부 @default true */
+    enabled?: boolean;
+}
+interface MagneticCursorReturn<T extends HTMLElement = HTMLElement> {
+    /** 자석 대상 요소에 연결할 ref */
+    ref: React.RefObject<T | null>;
+    /** 마우스 이벤트 핸들러 */
+    handlers: {
+        onMouseMove: (e: React.MouseEvent) => void;
+        onMouseLeave: () => void;
+    };
+    /** 요소에 적용할 transform 스타일 */
+    style: CSSProperties;
+}
+/**
+ * useMagneticCursor - 자석 커서 효과 훅
+ *
+ * 마우스가 요소 근처에 오면 요소가 마우스 쪽으로 끌려오는 효과.
+ * 버튼, 아이콘 등에 적용하면 인터랙티브 느낌 향상.
+ *
+ * @example
+ * ```tsx
+ * const magnetic = useMagneticCursor<HTMLButtonElement>({ strength: 0.4 })
+ * return <button ref={magnetic.ref} style={magnetic.style} {...magnetic.handlers}>Click</button>
+ * ```
+ */
+declare function useMagneticCursor<T extends HTMLElement = HTMLElement>(options?: MagneticCursorOptions): MagneticCursorReturn<T>;
+
+interface SmoothScrollOptions {
+    /** 활성화 여부 @default true */
+    enabled?: boolean;
+    /** 스무딩 계수 (0-1, 낮을수록 부드러움) @default 0.1 */
+    lerp?: number;
+    /** 마우스 휠 배율 @default 1 */
+    wheelMultiplier?: number;
+    /** 터치 배율 @default 2 */
+    touchMultiplier?: number;
+    /** 방향 @default 'vertical' */
+    direction?: 'vertical' | 'horizontal';
+    /** 콜백: 스크롤 값 변경 시 */
+    onScroll?: (scroll: number) => void;
+}
+interface SmoothScrollReturn {
+    /** 현재 스크롤 위치 (smoothed) */
+    scroll: number;
+    /** 목표 스크롤 위치 */
+    targetScroll: number;
+    /** 스크롤 진행률 (0-1) */
+    progress: number;
+    /** 특정 위치로 스크롤 */
+    scrollTo: (target: number | HTMLElement, options?: {
+        offset?: number;
+    }) => void;
+    /** 스크롤 중지 */
+    stop: () => void;
+}
+/**
+ * useSmoothScroll - 부드러운 스크롤 훅
+ *
+ * lenis 스타일의 smooth scrolling. 네이티브 스크롤을 가로채서
+ * lerp 보간으로 부드러운 스크롤 경험을 제공합니다.
+ *
+ * @example
+ * ```tsx
+ * const { scroll, progress, scrollTo } = useSmoothScroll({ lerp: 0.08 })
+ * return <button onClick={() => scrollTo(document.getElementById('section')!)}>Go</button>
+ * ```
+ */
+declare function useSmoothScroll(options?: SmoothScrollOptions): SmoothScrollReturn;
+
+interface ElementProgressOptions {
+    /** 요소가 뷰포트 아래에서 시작되는 위치 (0 = 하단, 1 = 상단) @default 0 */
+    start?: number;
+    /** 요소가 뷰포트 위에서 끝나는 위치 @default 1 */
+    end?: number;
+    /** 클램프 여부 @default true */
+    clamp?: boolean;
+}
+interface ElementProgressReturn<T extends HTMLElement = HTMLElement> {
+    /** 대상 요소 ref */
+    ref: React.RefObject<T | null>;
+    /** 요소의 스크롤 진행률 (0-1) */
+    progress: number;
+    /** 요소가 뷰포트 안에 있는지 */
+    isInView: boolean;
+}
+/**
+ * useElementProgress - 요소 단위 스크롤 진행률 훅
+ *
+ * useScrollProgress의 확장판. 페이지 전체가 아니라
+ * 특정 요소가 뷰포트를 통과하는 진행률을 추적합니다.
+ *
+ * @example
+ * ```tsx
+ * const { ref, progress, isInView } = useElementProgress<HTMLDivElement>()
+ * return (
+ *   <div ref={ref} style={{ opacity: progress }}>
+ *     Fades in as you scroll
+ *   </div>
+ * )
+ * ```
+ */
+declare function useElementProgress<T extends HTMLElement = HTMLElement>(options?: ElementProgressOptions): ElementProgressReturn<T>;
+
 declare const MOTION_PRESETS: PresetConfig;
 declare const PAGE_MOTIONS: Record<PageType, PageMotionsConfig>;
 /**
@@ -1086,4 +1290,77 @@ declare const easingPresets: {
 };
 declare function getPresetEasing(preset: keyof typeof easingPresets): EasingFunction;
 
-export { type BaseMotionOptions, type BaseMotionReturn, type BounceOptions, type EasingFunction, type EasingType, type EntranceType, type FadeInOptions, type GestureConfig, type GestureOptions$1 as GestureOptions, type GradientOptions, type HoverMotionOptions, type InViewOptions, type InViewReturn, type InteractionReturn, MOTION_PRESETS, type Motion, type MotionCallback, type MotionConfig, type MotionDirection$1 as MotionDirection, type MotionEasing, type MotionElement, MotionEngine, type MotionFrame, type MotionOptions, type MotionPreset, type MotionProgressCallback, type MotionState$1 as MotionState, type MotionStateCallback, type MotionTrigger, type MotionType$1 as MotionType, type MouseOptions, type MouseReturn, type OptimizationConfig, type OrchestrationConfig, PAGE_MOTIONS, type PageMotionElement, type PageMotionRef, type PageMotionsConfig, type PageType, type PerformanceMetrics, PerformanceOptimizer, type PerformanceOptimizerMetrics, type PresetConfig, type PulseOptions, type ReducedMotionReturn, type RepeatOptions, type ScaleOptions, type ScrollRevealMotionType, type ScrollRevealOptions, type SlideOptions, type SpringConfig, type SpringOptions, type ToggleMotionOptions, TransitionEffects, type TransitionOptions, type TransitionType, type UseUnifiedMotionOptions, type WindowSizeOptions, type WindowSizeReturn, applyEasing, easeIn, easeInOut, easeInOutQuad, easeInQuad, easeOut, easeOutQuad, easingPresets, getAvailableEasings, getEasing, getMotionPreset, getPagePreset, getPresetEasing, isEasingFunction, isValidEasing, linear, mergeWithPreset, motionEngine, performanceOptimizer, safeApplyEasing, transitionEffects, useBounceIn, useClickToggle, useFadeIn, useFocusToggle, useGesture, useGestureMotion, useGradient, useHoverMotion, useInView, useMotionState, useMouse, usePageMotions, usePulse, useReducedMotion, useRepeat, useScaleIn, useScrollProgress, useScrollReveal, useSimplePageMotion, useSlideDown, useSlideLeft, useSlideRight, useSlideUp, useSmartMotion, useSpringMotion, useToggleMotion, useUnifiedMotion, useWindowSize };
+type MotionAs = 'div' | 'span' | 'section' | 'article' | 'header' | 'footer' | 'main' | 'nav';
+interface MotionProps extends react__default.HTMLAttributes<HTMLElement> {
+    /** HTML 요소 타입 @default 'div' */
+    as?: MotionAs;
+    /** 모션 타입 */
+    type?: EntranceType;
+    /** 멀티이펙트 */
+    effects?: MotionEffects;
+    /** 스크롤 기반 reveal 모드 */
+    scroll?: boolean | ScrollRevealOptions;
+    /** 딜레이 (ms) */
+    delay?: number;
+    /** 지속시간 (ms) */
+    duration?: number;
+    children: react__default.ReactNode;
+}
+/**
+ * Motion wrapper component
+ *
+ * ref/style 수동 연결 없이 모션을 적용하는 래퍼 컴포넌트.
+ *
+ * @example
+ * // 기본 fadeIn
+ * <Motion>content</Motion>
+ *
+ * // 스크롤 reveal
+ * <Motion scroll delay={200} className="grid grid-cols-3">...</Motion>
+ *
+ * // 커스텀 요소 + 타입
+ * <Motion as="section" type="slideUp" duration={800}>...</Motion>
+ */
+declare function Motion({ as: Component, type, effects, scroll, delay, duration, children, className, style: userStyle, ...rest }: MotionProps): react_jsx_runtime.JSX.Element;
+
+interface UseStaggerOptions {
+    /** 자식 아이템 개수 */
+    count: number;
+    /** 아이템 간 딜레이 (ms) @default 100 */
+    staggerDelay?: number;
+    /** 전체 시작 딜레이 (ms) @default 0 */
+    baseDelay?: number;
+    /** 애니메이션 지속시간 (ms) @default 700 */
+    duration?: number;
+    /** 모션 타입 @default 'fadeIn' */
+    motionType?: ScrollRevealMotionType;
+    /** IntersectionObserver 임계값 @default 0.1 */
+    threshold?: number;
+    /** 이징 함수 @default 'ease-out' */
+    easing?: string;
+}
+interface UseStaggerReturn {
+    /** 부모 컨테이너 ref — IntersectionObserver 연결 */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** 자식 아이템별 style 배열 */
+    styles: CSSProperties[];
+    /** 전체 visible 여부 */
+    isVisible: boolean;
+}
+/**
+ * useStagger — 리스트 아이템에 순차 딜레이를 적용하는 훅
+ *
+ * 단일 IntersectionObserver로 컨테이너를 관찰하고,
+ * 자식 아이템별로 CSS transition-delay를 자동 계산합니다.
+ *
+ * @example
+ * const stagger = useStagger({ count: items.length, staggerDelay: 100 });
+ * <div ref={stagger.containerRef}>
+ *   {items.map((item, i) => (
+ *     <div style={stagger.styles[i]} key={i}>{item}</div>
+ *   ))}
+ * </div>
+ */
+declare function useStagger(options: UseStaggerOptions): UseStaggerReturn;
+
+export { type BaseMotionOptions, type BaseMotionReturn, type BounceOptions, type CustomCursorOptions, type CustomCursorReturn, type EasingFunction, type EasingType, type ElementProgressOptions, type ElementProgressReturn, type EntranceType, type FadeInOptions, type GestureConfig, type GestureOptions$1 as GestureOptions, type GradientOptions, type HoverMotionOptions, type InViewOptions, type InViewReturn, type InteractionReturn, MOTION_PRESETS, type MagneticCursorOptions, type MagneticCursorReturn, Motion, type MotionCallback, type MotionConfig, type MotionDirection$1 as MotionDirection, type MotionEasing, type MotionEffects, type MotionElement, MotionEngine, type MotionFrame, type Motion$1 as MotionInstance, type MotionOptions, type MotionPreset, type MotionProgressCallback, type MotionProps, type MotionState$1 as MotionState, type MotionStateCallback, type MotionTrigger, type MotionType$1 as MotionType, type MouseOptions, type MouseReturn, type OptimizationConfig, type OrchestrationConfig, PAGE_MOTIONS, type PageMotionElement, type PageMotionRef, type PageMotionsConfig, type PageType, type PerformanceMetrics, PerformanceOptimizer, type PerformanceOptimizerMetrics, type PresetConfig, type PulseOptions, type ReducedMotionReturn, type RepeatOptions, type ScaleOptions, type ScrollRevealMotionType, type ScrollRevealOptions, type SlideOptions, type SmoothScrollOptions, type SmoothScrollReturn, type SpringConfig, type SpringOptions, type ToggleMotionOptions, TransitionEffects, type TransitionOptions, type TransitionType, type TypewriterOptions, type TypewriterReturn, type UseStaggerOptions, type UseStaggerReturn, type UseUnifiedMotionOptions, type WindowSizeOptions, type WindowSizeReturn, applyEasing, easeIn, easeInOut, easeInOutQuad, easeInQuad, easeOut, easeOutQuad, easingPresets, getAvailableEasings, getEasing, getMotionPreset, getPagePreset, getPresetEasing, isEasingFunction, isValidEasing, linear, mergeWithPreset, motionEngine, performanceOptimizer, safeApplyEasing, transitionEffects, useBounceIn, useClickToggle, useCustomCursor, useElementProgress, useFadeIn, useFocusToggle, useGesture, useGestureMotion, useGradient, useHoverMotion, useInView, useMagneticCursor, useMotionState, useMouse, usePageMotions, usePulse, useReducedMotion, useRepeat, useScaleIn, useScrollProgress, useScrollReveal, useSimplePageMotion, useSlideDown, useSlideLeft, useSlideRight, useSlideUp, useSmartMotion, useSmoothScroll, useSpringMotion, useStagger, useToggleMotion, useTypewriter, useUnifiedMotion, useWindowSize };