MotionEngine / TransitionEffects

stable

순수 JavaScript 기반 저수준 모션 엔진 — DOM 의존성 없는 코어 클래스

@hua-labs/motion-corev2.0.0

Import

import { motionEngine, MotionEngine } from '@hua-labs/motion-core'
import { transitionEffects, TransitionEffects } from '@hua-labs/motion-core'

MotionEngine

GPU 가속과 레이어 분리 최적화가 내장된 순수 JavaScript 모션 엔진이다. 싱글톤 motionEngine 인스턴스를 통해 사용하는 것을 권장한다.

타입

interface MotionFrame {
  progress: number // 0 ~ 1
  properties: {
    opacity?: number
    transform?: string
    scale?: number
    translateX?: number
    translateY?: number
    rotate?: number
    rotateX?: number
    rotateY?: number
    rotateZ?: number
    skewX?: number
    skewY?: number
  }
}

interface MotionOptions {
  duration: number
  easing: (t: number) => number
  delay?: number
  direction?: 'forward' | 'reverse' | 'alternate'
  iterations?: number
  fill?: 'none' | 'forwards' | 'backwards' | 'both'
  onStart?: () => void
  onUpdate?: (progress: number) => void
  onComplete?: () => void
  onCancel?: () => void
}

interface Motion {
  id: string
  element: HTMLElement
  isRunning: boolean
  isPaused: boolean
  currentProgress: number
  startTime: number
  pauseTime: number
  options: MotionOptions
}

메서드

메서드	시그니처	설명
`motion`	`(element, frames, options) => Promise<string>`	모션 시작, motionId 반환
`stop`	`(motionId: string) => void`	특정 모션 중지
`pause`	`(motionId: string) => void`	특정 모션 일시정지
`resume`	`(motionId: string) => void`	일시정지된 모션 재개
`stopAll`	`() => void`	모든 모션 중지
`getMotion`	`(motionId: string) => Motion \	undefined`	모션 상태 조회
`getActiveMotionCount`	`() => number`	실행 중인 모션 수
`destroy`	`() => void`	엔진 정리

Usage

import { motionEngine, easeOut } from '@hua-labs/motion-core'

const element = document.querySelector('#my-element') as HTMLElement

const motionId = await motionEngine.motion(
  element,
  [
    { progress: 0, properties: { opacity: 0, translateY: 20 } },
    { progress: 1, properties: { opacity: 1, translateY: 0 } }
  ],
  {
    duration: 500,
    easing: easeOut,
    onComplete: () => console.log('완료')
  }
)

// 일시정지 / 재개
motionEngine.pause(motionId)
motionEngine.resume(motionId)

// 중지
motionEngine.stop(motionId)

TransitionEffects

MotionEngine 위에 구축된 고수준 전환 효과 클래스다. 싱글톤 패턴 TransitionEffects.getInstance()와 transitionEffects 인스턴스를 제공한다.

TransitionType

type TransitionType =
  | 'fade'
  | 'slide'
  | 'slide-up'
  | 'slide-down'
  | 'slide-left'
  | 'slide-right'
  | 'scale'
  | 'flip'
  | 'morph'
  | 'cube'
  | 'zoom'

TransitionOptions

interface TransitionOptions extends Omit<MotionOptions, 'easing'> {
  type: TransitionType
  easing?: (t: number) => number
  distance?: number      // slide 거리 (px)
  scale?: number         // scale 시작/끝 값
  perspective?: number   // 3D 효과를 위한 원근감 (px)
  onTransitionStart?: () => void
  onTransitionComplete?: () => void
}

메서드

메서드	시그니처	설명
`fade`	`(element, options) => Promise<void>`	페이드 인/아웃 전환
`slide`	`(element, options) => Promise<void>`	슬라이드 전환
`scale`	`(element, options) => Promise<void>`	스케일 전환
`flip`	`(element, options) => Promise<void>`	3D 플립 전환
`cube`	`(element, options) => Promise<void>`	3D 큐브 회전 전환
`morph`	`(element, options) => Promise<void>`	스케일 + 회전 복합 전환
`stopTransition`	`(transitionId: string) => void`	특정 전환 중지
`stopAllTransitions`	`() => void`	모든 전환 중지
`getActiveTransitionCount`	`() => number`	활성 전환 수
`destroy`	`() => void`	인스턴스 정리

Usage

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

const element = document.querySelector('#card') as HTMLElement

// 페이드 인
await transitionEffects.fade(element, {
  duration: 400,
  direction: 'forward'
})

// 3D 플립
await transitionEffects.flip(element, {
  duration: 600,
  perspective: 1000
})

// 슬라이드 아웃
await transitionEffects.slide(element, {
  duration: 300,
  distance: 200,
  direction: 'reverse'
})

Notes

motionEngine과 transitionEffects는 모두 싱글톤이므로 앱 전역에서 같은 인스턴스를 공유한다.
일반 React 컴포넌트에서는 저수준 엔진 대신 훅(useFadeIn, useSlideUp 등)을 사용하는 것을 권장한다.
MotionEngine은 DOM에 직접 접근하므로 SSR 환경에서는 주의가 필요하다.