@hua-labs/motion-core 2.1.0-alpha.1 → 2.1.0-alpha.10

package/README.md

@@ -1,276 +1,92 @@
 # @hua-labs/motion-core
 
-30+ production-tested React animation hooks. Zero dependencies, SSR-ready.
-프로덕션 검증 완료 React 애니메이션 훅 30개 이상. 의존성 없음, SSR 지원.
+Production-ready React animation hooks — zero dependencies, SSR-ready.
+프로덕션 레디 React 애니메이션 훅 — 의존성 없음, SSR 지원.
 
 [![npm version](https://img.shields.io/npm/v/@hua-labs/motion-core.svg)](https://www.npmjs.com/package/@hua-labs/motion-core)
+[![npm downloads](https://img.shields.io/npm/dw/@hua-labs/motion-core.svg)](https://www.npmjs.com/package/@hua-labs/motion-core)
 [![license](https://img.shields.io/npm/l/@hua-labs/motion-core.svg)](https://github.com/HUA-Labs/HUA-Labs-public/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-19-blue)](https://reactjs.org/)
 
-> **⚠️ Alpha Release**: This package is currently in alpha. APIs may change before the stable release.
+> **Alpha**: APIs may change before stable release. | **알파**: 안정 릴리스 전 API가 변경될 수 있습니다.
 
----
+## Overview | 개요
 
-## English
+A collection of 25+ React animation hooks built on a ref-based engine. Direct DOM manipulation for consistent performance with zero external dependencies. All hooks are TypeScript-native and SSR-compatible.
 
-### Overview
+ref 기반 엔진으로 구축된 25개 이상의 React 애니메이션 훅 컬렉션입니다. 외부 의존성 없이 직접 DOM 조작으로 일관된 성능을 제공합니다. 모든 훅은 TypeScript 네이티브이며 SSR 호환됩니다.
 
-A production-ready collection of 30+ motion hooks optimized for React. Built on a ref-based engine that delivers smooth 60fps animations with zero external dependencies. Every hook is TypeScript-native and SSR-compatible.
+## Features
 
-### Why motion-core?
+- **25+ animation hooks** — Fade, slide, scale, scroll, interactions, gestures
+- **Zero dependencies** — Pure JavaScript motion engine
+- **Ref-based** — Direct DOM manipulation for consistent performance
+- **SSR compatible** — Works with Next.js, Remix, and SSR frameworks
+- **Tested** — 517 test cases
 
-motion-core provides essential animation primitives for React applications through direct DOM manipulation. The ref-based approach offers predictable performance characteristics while maintaining a small bundle footprint.
-
-### Key Features
-
-- **30+ Optimized Hooks** - Fade, slide, scale, scroll, parallax, and gesture animations
-- **Performance First** - Direct ref manipulation for consistent 60fps
-- **Zero Dependencies** - Pure JavaScript motion engine (~15KB gzipped)
-- **TypeScript Native** - Complete type safety with inferred types
-- **SSR Compatible** - Works with Next.js, Remix, and all SSR frameworks
-- **Battle Tested** - 74%+ coverage with 517 test cases
-
-### Installation
-
-```bash
-npm install @hua-labs/motion-core
-```
-
-```bash
-yarn add @hua-labs/motion-core
-```
+## Installation | 설치
 
 ```bash
 pnpm add @hua-labs/motion-core
 ```
 
-## Quick Start
+Peer dependencies: `react >= 19.0.0`, `react-dom >= 19.0.0`
+
+## Quick Start | 빠른 시작
 
 ```tsx
-import React from 'react';
 import { useFadeIn, useSlideUp } from '@hua-labs/motion-core';
 
-function MyComponent() {
+function Hero() {
   const fadeIn = useFadeIn({ duration: 800 });
   const slideUp = useSlideUp({ delay: 200 });
 
   return (
     <div>
-      <h1 ref={fadeIn.ref} style={fadeIn.style}>
-        Welcome to HUA Motion Core
-      </h1>
-      <p ref={slideUp.ref} style={slideUp.style}>
-        Beautiful animations made simple
-      </p>
+      <h1 ref={fadeIn.ref} style={fadeIn.style}>Welcome</h1>
+      <p ref={slideUp.ref} style={slideUp.style}>Animated content</p>
     </div>
   );
 }
 ```
 
-## Available Hooks
-
-### Basic Motion Hooks (9)
-- `useFadeIn` - Fade in animation
-- `useSlideUp` - Slide up animation  
-- `useSlideLeft` - Slide left animation
-- `useSlideRight` - Slide right animation
-- `useSlideDown` - Advanced slide down with bounce/overshoot
-- `useScaleIn` - Scale in animation
-- `useBounceIn` - Bounce in animation
-- `usePulse` - Pulse animation
-- `useSkeleton` - Skeleton loading animation
-
-### Interaction Hooks (4)
-- `useHoverMotion` - Hover-triggered animations
-- `useClickToggle` - Click-triggered animations
-- `useFocusToggle` - Focus-triggered animations
-- `useVisibilityToggle` - Visibility-controlled animations
-
-### Scroll Hooks (3)
-- `useScrollReveal` - Scroll-triggered reveal animations
-- `useScrollToggle` - Scroll-based toggle animations
-- `useScrollProgress` - Scroll progress tracking
-
-### Utility Hooks (2)
-- `useMotionState` - Motion state management
-- `useRepeat` - Repeating animations
-
-### Advanced Hooks (7)
-- `useMotion` - Core motion engine
-- `useSpringMotion` - Spring physics animations
-- `useGradient` - Gradient animations
-- `useNavigation` - Navigation animations
-- `useButtonEffect` - Button interaction effects
-- `useCardList` - Card list animations
-- `useLoadingSpinner` - Loading spinner animations
-
-## API Reference
-
-All hooks return a consistent interface:
-
-```tsx
-interface BaseMotionReturn<T = HTMLElement> {
-  ref: RefObject<T>;
-  style: CSSProperties;
-  isVisible: boolean;
-  isAnimating: boolean;
-  progress: number;
-  start: () => void;
-  stop: () => void;
-  reset: () => void;
-  pause: () => void;
-  resume: () => void;
-}
-```
-
-### Common Options
+## API Overview | API 개요
 
-```tsx
-interface BaseMotionOptions {
-  duration?: number;        // Animation duration in ms (default: 1000)
-  delay?: number;          // Animation delay in ms (default: 0)
-  easing?: string;         // CSS easing function (default: 'ease-out')
-  autoStart?: boolean;     // Auto-start animation (default: true)
-  onStart?: () => void;    // Start callback
-  onComplete?: () => void; // Complete callback
-  onStop?: () => void;     // Stop callback
-  onReset?: () => void;    // Reset callback
-}
-```
+All hooks return a consistent `BaseMotionReturn` interface:
 
-## Examples
+| Property | Type | Description |
+|----------|------|-------------|
+| `ref` | `RefObject<T>` | Attach to target element |
+| `style` | `CSSProperties` | Apply to element |
+| `isVisible` | `boolean` | Visibility state |
+| `isAnimating` | `boolean` | Animation in progress |
+| `start/stop/reset/pause/resume` | `() => void` | Playback controls |
 
-### Fade In Animation
+**Available hooks by category:**
 
-```tsx
-import { useFadeIn } from '@hua-labs/motion-core';
+| Category | Hooks |
+|----------|-------|
+| Basic | `useFadeIn`, `useSlideUp`, `useSlideLeft`, `useSlideRight`, `useScaleIn`, `useBounceIn`, `usePulse`, `useSpringMotion`, `useGradient` |
+| Interaction | `useHoverMotion`, `useClickToggle`, `useFocusToggle`, `useToggleMotion` |
+| Scroll | `useScrollReveal`, `useScrollProgress` |
+| List | `useStaggerMotion`, `useCardList`, `useSkeleton` |
+| Utility | `useMotionState`, `useRepeat`, `useSmartMotion`, `useUnifiedMotion`, `useSimplePageMotion`, `usePageMotions`, `useGesture`, `useGestureMotion` |
 
-function FadeInExample() {
-  const { ref, style, start, stop } = useFadeIn({
-    duration: 1000,
-    autoStart: false
-  });
+## Documentation | 문서
 
-  return (
-    <div>
-      <div ref={ref} style={style}>
-        This will fade in
-      </div>
-      <button onClick={start}>Start</button>
-      <button onClick={stop}>Stop</button>
-    </div>
-  );
-}
-```
+- [Detailed Guide](./DETAILED_GUIDE.md)
+- [📚 Documentation Site | 문서 사이트](https://docs.hua-labs.com)
 
-### Scroll Reveal
-
-```tsx
-import { useScrollReveal } from '@hua-labs/motion-core';
-
-function ScrollRevealExample() {
-  const { ref, style } = useScrollReveal({
-    threshold: 0.3,
-    triggerOnce: true
-  });
-
-  return (
-    <div ref={ref} style={style}>
-      This appears when scrolled into view
-    </div>
-  );
-}
-```
-
-### Hover Interaction
-
-```tsx
-import { useHoverMotion } from '@hua-labs/motion-core';
-
-function HoverExample() {
-  const { ref, style, hover, leave } = useHoverMotion({
-    scale: 1.1,
-    duration: 300
-  });
-
-  return (
-    <div 
-      ref={ref} 
-      style={style}
-      onMouseEnter={hover}
-      onMouseLeave={leave}
-    >
-      Hover me!
-    </div>
-  );
-}
-```
-
-## TypeScript Support
-
-HUA Motion Core is built with TypeScript and provides comprehensive type definitions:
-
-```tsx
-import { useFadeIn, BaseMotionReturn, FadeInOptions } from '@hua-labs/motion-core';
-
-// Full type safety
-const fadeIn: BaseMotionReturn<HTMLDivElement> = useFadeIn({
-  duration: 1000,
-  opacity: { from: 0, to: 1 }
-} as FadeInOptions);
-```
-
-## Related Packages
-
-- **[@hua-labs/motion-advanced](../../hua-motion-advanced)** - Advanced motion hooks and orchestration
-- **[@hua-labs/motion](../../hua-motion)** - Unified package (Core + Advanced re-export)
-
-## Roadmap
-
-- **Motion Core** - Essential hooks ✅ (Current)
-- **Motion Advanced** - Complex animations ✅ (Available)
-- **Motion Enterprise** - Team solutions (Planned)
-
-### Documentation
-
-- [Detailed Guide](./DETAILED_GUIDE.md) - Complete API reference and advanced usage
-- [TypeScript Definitions](./dist/index.d.ts) - Type definitions
-
-### Browser Support
-
-- Chrome 60+
-- Firefox 60+
-- Safari 12+
-- Edge 79+
-
----
-
-## Korean
-
-### 개요
-
-React를 위한 프로덕션 준비 완료 모션 훅 30개 이상의 컬렉션입니다. 외부 의존성 없이 부드러운 60fps 애니메이션을 제공하는 ref 기반 엔진으로 구축되었습니다. 모든 훅은 TypeScript 네이티브이며 SSR과 호환됩니다.
-
-### 주요 기능
-
-- **30개 이상의 최적화된 훅** - 페이드, 슬라이드, 스케일, 스크롤, 패럴랙스, 제스처 애니메이션
-- **성능 우선** - 일관된 60fps를 위한 직접 ref 조작
-- **의존성 없음** - 순수 JavaScript 모션 엔진 (~15KB gzipped)
-- **TypeScript 네이티브** - 타입 추론이 포함된 완전한 타입 안전성
-- **SSR 호환** - Next.js, Remix 및 모든 SSR 프레임워크와 작동
-- **검증 완료** - 517개 테스트 케이스로 74% 이상 커버리지
-
-### 설치
-
-```bash
-npm install @hua-labs/motion-core
-```
+## Related Packages | 관련 패키지
 
-### 문서
+- [`@hua-labs/pro`](https://www.npmjs.com/package/@hua-labs/pro) — Advanced motion hooks (orchestration, auto-animations)
+- [`@hua-labs/hua-ux`](https://www.npmjs.com/package/@hua-labs/hua-ux) — UX framework (includes motion)
 
-- [상세 가이드](./DETAILED_GUIDE.md) - 완전한 API 레퍼런스 및 고급 사용법
+## Requirements | 요구사항
 
----
+React >= 19.0.0 · React DOM >= 19.0.0 · TypeScript >= 5.9
 
 ## License
 
-MIT © HUA Labs
+MIT — [HUA Labs](https://github.com/HUA-Labs/HUA-Labs-public)