통합 모션 훅

stable

단일 인터페이스로 여러 모션 효과를 선택하거나 결합하는 통합 훅

@hua-labs/motion-corev2.0.0

Import

import { useUnifiedMotion, useSmartMotion } from '@hua-labs/motion-core'

useUnifiedMotion

단일 타입 선택 모드와 복수 효과 결합 모드를 모두 지원하는 통합 입장 애니메이션 훅이다. 내부적으로 선택된 타입에 맞는 로직만 실행하여 성능을 최적화한다.

Signature

function useUnifiedMotion<T extends MotionElement = HTMLDivElement>(
  options: UseUnifiedMotionOptions
): BaseMotionReturn<T>

interface UseUnifiedMotionOptions extends Omit<BaseMotionOptions, 'autoStart'> {
  type?: EntranceType        // 단일 효과 모드
  effects?: MotionEffects    // 복수 효과 결합 모드
  autoStart?: boolean        // 기본값: true
  distance?: number          // slide 거리 (px, 기본값: 50)
  duration?: number
  delay?: number
  easing?: string
  threshold?: number
  triggerOnce?: boolean
}

EntranceType

type EntranceType =
  | 'fadeIn'
  | 'slideUp'
  | 'slideLeft'
  | 'slideRight'
  | 'scaleIn'
  | 'bounceIn'

MotionEffects (복수 효과 결합)

interface MotionEffects {
  fade?: boolean | { targetOpacity?: number }
  slide?: boolean | { direction?: 'up' | 'down' | 'left' | 'right'; distance?: number }
  scale?: boolean | { from?: number; to?: number }
  bounce?: boolean
}

Usage — 단일 타입 모드

import { useUnifiedMotion } from '@hua-labs/motion-core'

function HeroTitle() {
  const { ref, style } = useUnifiedMotion({
    type: 'slideUp',
    delay: 200,
    duration: 700
  })

  return <h1 ref={ref} style={style}>환영합니다</h1>
}

Usage — 복수 효과 결합 모드

import { useUnifiedMotion } from '@hua-labs/motion-core'

function FancyCard() {
  const { ref, style } = useUnifiedMotion({
    effects: {
      fade: true,
      slide: { direction: 'up', distance: 30 },
      scale: { from: 0.95, to: 1 }
    },
    duration: 600,
    delay: 100
  })

  return <div ref={ref} style={style}>카드</div>
}

Returns

BaseMotionReturn<T> 타입을 반환한다.

이름	타입	설명
`ref`	`RefObject<T>`	DOM 요소 참조
`style`	`MotionStyle`	CSS 스타일
`isVisible`	`boolean`	가시성 여부
`isAnimating`	`boolean`	애니메이션 진행 여부
`progress`	`number`	진행률 (0~1)
`start`	`() => void`	시작
`stop`	`() => void`	중지
`reset`	`() => void`	리셋

useSmartMotion

요소 타입(hero, title, button, card, text, image)과 인터랙션 설정을 기반으로 모션을 자동 구성하는 레거시 훅이다. 내부적으로 MOTION_PRESETS를 참조한다.

Signature

function useSmartMotion<T extends HTMLElement = HTMLDivElement>(
  options?: SmartMotionOptions
): {
  ref: RefObject<T | null>
  style: CSSProperties
  isVisible: boolean
  isHovered: boolean
  isClicked: boolean
}

interface SmartMotionOptions {
  type?: 'hero' | 'title' | 'button' | 'card' | 'text' | 'image'
  entrance?: MotionType
  hover?: boolean
  click?: boolean
  delay?: number
  duration?: number
  threshold?: number
  autoLanguageSync?: boolean
}

type MotionType = 'fadeIn' | 'slideUp' | 'slideLeft' | 'slideRight' | 'scaleIn' | 'bounceIn'

Parameters

파라미터	타입	기본값	설명
`type`	`ElementType`	`'text'`	요소 타입 (프리셋 기반 설정 자동 적용)
`entrance`	`MotionType`	타입별 프리셋	입장 애니메이션 타입
`hover`	`boolean`	타입별 프리셋	호버 효과 활성화
`click`	`boolean`	타입별 프리셋	클릭 효과 활성화
`delay`	`number`	타입별 프리셋	지연 시간 (ms)
`duration`	`number`	타입별 프리셋	지속 시간 (ms)
`threshold`	`number`	`0.1`	Intersection Observer 임계값

타입별 기본 프리셋

타입	입장 효과	딜레이	호버	클릭
`hero`	`fadeIn`	200ms	X	X
`title`	`slideUp`	400ms	X	X
`button`	`scaleIn`	600ms	O	O
`card`	`slideUp`	800ms	O	X
`text`	`fadeIn`	200ms	X	X
`image`	`scaleIn`	400ms	O	X

Usage

import { useSmartMotion } from '@hua-labs/motion-core'

function ProductPage() {
  const hero = useSmartMotion({ type: 'hero' })
  const title = useSmartMotion({ type: 'title' })
  const buyButton = useSmartMotion({ type: 'button' })

  return (
    <div>
      <div ref={hero.ref} style={hero.style}>히어로 이미지</div>
      <h1 ref={title.ref} style={title.style}>제품명</h1>
      <button
        ref={buyButton.ref}
        style={buyButton.style}
      >
        구매하기
      </button>
    </div>
  )
}

Notes

useUnifiedMotion이 useSmartMotion의 후속 API다. 신규 코드에서는 useUnifiedMotion을 권장한다.
type과 effects를 동시에 지정하면 effects 모드가 우선 적용된다.
bounceIn 타입은 자동으로 cubic-bezier(0.34, 1.56, 0.64, 1) 이징이 적용된다.
autoLanguageSync: true는 localStorage 변경을 감지하여 모션을 재시작한다. i18n 언어 전환 시 활용할 수 있다.