@hua-labs/motion-core 2.2.3 → 2.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +128 -39
- package/dist/chunk-47QAGQLN.mjs +1057 -0
- package/dist/chunk-47QAGQLN.mjs.map +1 -0
- package/dist/chunk-LSIP7MB5.cjs +1090 -0
- package/dist/chunk-LSIP7MB5.cjs.map +1 -0
- package/dist/index.cjs +7532 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.mts +834 -642
- package/dist/index.d.ts +834 -642
- package/dist/index.mjs +4393 -1744
- package/dist/index.mjs.map +1 -1
- package/dist/native.cjs +692 -0
- package/dist/native.cjs.map +1 -0
- package/dist/native.d.mts +177 -0
- package/dist/native.d.ts +177 -0
- package/dist/native.mjs +555 -0
- package/dist/native.mjs.map +1 -0
- package/dist/springPhysics-DLyZ4nbx.d.mts +687 -0
- package/dist/springPhysics-DLyZ4nbx.d.ts +687 -0
- package/package.json +31 -11
- package/dist/index.js +0 -4756
- package/dist/index.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,20 +1,22 @@
|
|
|
1
1
|
# @hua-labs/motion-core
|
|
2
2
|
|
|
3
|
-
A collection of
|
|
3
|
+
A collection of 55+ 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. React Native support via dedicated native hooks using the Animated API.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@hua-labs/motion-core)
|
|
6
6
|
[](https://www.npmjs.com/package/@hua-labs/motion-core)
|
|
7
|
-
[](https://github.com/HUA-Labs/
|
|
7
|
+
[](https://github.com/HUA-Labs/hua-packages/blob/main/LICENSE)
|
|
8
8
|
[](https://www.typescriptlang.org/)
|
|
9
9
|
[](https://reactjs.org/)
|
|
10
10
|
|
|
11
11
|
## Features
|
|
12
12
|
|
|
13
|
-
- **
|
|
13
|
+
- **55+ animation hooks — Fade, slide, scale, scroll, interactions, gestures, orchestration**
|
|
14
14
|
- **Zero dependencies — Pure JavaScript motion engine**
|
|
15
15
|
- **Ref-based — Direct DOM manipulation for consistent performance**
|
|
16
16
|
- **SSR compatible — Works with Next.js, Remix, and SSR frameworks**
|
|
17
|
+
- **React Native — 10 native hooks via Animated API (separate entry point)**
|
|
17
18
|
- **Fully tested — Comprehensive test coverage**
|
|
19
|
+
- **Pro hooks included — 18 advanced hooks absorbed from @hua-labs/pro (auto-play, orchestration, game loop, and more)**
|
|
18
20
|
|
|
19
21
|
## Installation
|
|
20
22
|
|
|
@@ -22,12 +24,12 @@ A collection of 35+ React animation hooks built on a ref-based engine. Direct DO
|
|
|
22
24
|
pnpm add @hua-labs/motion-core
|
|
23
25
|
```
|
|
24
26
|
|
|
25
|
-
> Peer dependencies: react >=19.0.0, react-dom >=19.0.0
|
|
27
|
+
> Peer dependencies: react >=19.0.0, react-dom >=19.0.0, react-native >=0.73.0
|
|
26
28
|
|
|
27
29
|
## Quick Start
|
|
28
30
|
|
|
29
31
|
```tsx
|
|
30
|
-
import { useFadeIn, useSlideUp } from
|
|
32
|
+
import { useFadeIn, useSlideUp } from "@hua-labs/motion-core";
|
|
31
33
|
|
|
32
34
|
function Hero() {
|
|
33
35
|
const fadeIn = useFadeIn({ duration: 800 });
|
|
@@ -35,48 +37,135 @@ function Hero() {
|
|
|
35
37
|
|
|
36
38
|
return (
|
|
37
39
|
<div>
|
|
38
|
-
<h1 ref={fadeIn.ref} style={fadeIn.style}>
|
|
39
|
-
|
|
40
|
+
<h1 ref={fadeIn.ref} style={fadeIn.style}>
|
|
41
|
+
Welcome
|
|
42
|
+
</h1>
|
|
43
|
+
<p ref={slideUp.ref} style={slideUp.style}>
|
|
44
|
+
Animated content
|
|
45
|
+
</p>
|
|
40
46
|
</div>
|
|
41
47
|
);
|
|
42
48
|
}
|
|
43
49
|
|
|
50
|
+
// React Native — import from /native
|
|
51
|
+
import { useFadeIn, useStagger } from "@hua-labs/motion-core/native";
|
|
52
|
+
|
|
53
|
+
function ListItem() {
|
|
54
|
+
const fadeIn = useFadeIn({ duration: 400 });
|
|
55
|
+
return (
|
|
56
|
+
<Animated.View style={fadeIn.style}>
|
|
57
|
+
<Text>Hello</Text>
|
|
58
|
+
</Animated.View>
|
|
59
|
+
);
|
|
60
|
+
}
|
|
44
61
|
```
|
|
45
62
|
|
|
46
63
|
## API
|
|
47
64
|
|
|
48
|
-
| Export
|
|
49
|
-
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
65
|
+
| Export | Type | Description |
|
|
66
|
+
| -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
67
|
+
| `MotionEngine` | class | Zero-dependency pure JavaScript motion engine class |
|
|
68
|
+
| `motionEngine` | variable | Singleton instance of MotionEngine |
|
|
69
|
+
| `TransitionEffects` | class | Transition effect system class (fade, slide, scale, etc.) |
|
|
70
|
+
| `transitionEffects` | variable | Singleton instance of TransitionEffects |
|
|
71
|
+
| `useSimplePageMotion` | hook | Simple fade+slide page entrance animation |
|
|
72
|
+
| `usePageMotions` | hook | Multi-element page entrance orchestration |
|
|
73
|
+
| `useSmartMotion` | hook | Adaptive motion based on device performance |
|
|
74
|
+
| `useUnifiedMotion` | hook | All-in-one motion hook with presets |
|
|
75
|
+
| `useFadeIn` | hook | Fade-in animation hook |
|
|
76
|
+
| `useSlideUp` | hook | Slide-up entrance animation |
|
|
77
|
+
| `useSlideLeft` | hook | Slide-left entrance animation |
|
|
78
|
+
| `useSlideRight` | hook | Slide-right entrance animation |
|
|
79
|
+
| `useScaleIn` | hook | Scale-in entrance animation |
|
|
80
|
+
| `useBounceIn` | hook | Bounce-in entrance animation |
|
|
81
|
+
| `usePulse` | hook | Repeating pulse animation |
|
|
82
|
+
| `useSpringMotion` | hook | Spring physics animation |
|
|
83
|
+
| `useGradient` | hook | Animated gradient background |
|
|
84
|
+
| `useHoverMotion` | hook | Hover interaction animation |
|
|
85
|
+
| `useClickToggle` | hook | Click-triggered toggle animation |
|
|
86
|
+
| `useFocusToggle` | hook | Focus-triggered toggle animation |
|
|
87
|
+
| `useScrollReveal` | hook | Scroll-triggered reveal animation |
|
|
88
|
+
| `useScrollProgress` | hook | Scroll position as 0-1 progress value |
|
|
89
|
+
| `useMotionState` | hook | Animation state tracking (idle, running, complete) |
|
|
90
|
+
| `useRepeat` | hook | Repeating animation with configurable count |
|
|
91
|
+
| `useToggleMotion` | hook | Toggle between two animation states |
|
|
92
|
+
| `useSlideDown` | hook | Slide-down entrance animation |
|
|
93
|
+
| `useInView` | hook | IntersectionObserver-based visibility detection |
|
|
94
|
+
| `useMouse` | hook | Mouse position tracking |
|
|
95
|
+
| `useReducedMotion` | hook | Detect prefers-reduced-motion setting |
|
|
96
|
+
| `useWindowSize` | hook | Responsive window size tracking |
|
|
97
|
+
| `useGesture` | hook | Multi-gesture handler (drag, swipe, pinch) |
|
|
98
|
+
| `useGestureMotion` | hook | Gesture-driven motion animation |
|
|
99
|
+
| `useButtonEffect` | hook | Ripple / press feedback effect for buttons |
|
|
100
|
+
| `useVisibilityToggle` | hook | Animate an element in/out based on a boolean visibility flag |
|
|
101
|
+
| `useScrollToggle` | hook | Toggle animation state based on scroll position threshold |
|
|
102
|
+
| `useCardList` | hook | Staggered entrance animation for a list of cards |
|
|
103
|
+
| `useLoadingSpinner` | hook | Continuous rotation animation for loading spinners |
|
|
104
|
+
| `useNavigation` | hook | Slide/fade animation for navigation transitions |
|
|
105
|
+
| `useSkeleton` | hook | Shimmer animation for skeleton loading placeholders |
|
|
106
|
+
| `useTypewriter` | hook | Typewriter character-by-character text reveal animation |
|
|
107
|
+
| `useCustomCursor` | hook | Custom cursor tracking and animation |
|
|
108
|
+
| `useMagneticCursor` | hook | Magnetic cursor attraction effect for interactive elements |
|
|
109
|
+
| `useSmoothScroll` | hook | Smooth programmatic scroll with easing |
|
|
110
|
+
| `useElementProgress` | hook | Track an element's scroll progress as a 0–1 value |
|
|
111
|
+
| `useAutoFade` | hook | Auto-playing opacity animation with repeat, loop, and manual fadeIn/fadeOut controls |
|
|
112
|
+
| `useAutoPlay` | hook | Interval-driven step counter with pause-on-hover, pause-on-blur, and repeat controls |
|
|
113
|
+
| `useAutoScale` | hook | Auto-playing scale animation with bounce/elastic easing and manual scaleIn/scaleOut controls |
|
|
114
|
+
| `useAutoSlide` | hook | Auto-playing translate animation across eight directional presets with repeat and toggle |
|
|
115
|
+
| `useMotionOrchestra` | hook | Coordinate multiple named motion steps in sequential, parallel, or stagger playback mode |
|
|
116
|
+
| `useOrchestration` | hook | Timeline-based motion orchestration with seek, variable speed, reverse, and per-step callbacks |
|
|
117
|
+
| `useSequence` | hook | Run an ordered array of motion hooks one after another with optional delay and loop |
|
|
118
|
+
| `useLayoutMotion` | hook | Animate layout properties (width, height, flex, grid) between two style states |
|
|
119
|
+
| `useKeyboardToggle` | hook | Toggle a boolean state with configurable key bindings, combos, and optional auto-reset |
|
|
120
|
+
| `useScrollDirection` | hook | Detect current scroll direction (up / down / idle) with a configurable threshold |
|
|
121
|
+
| `useStickyToggle` | hook | Boolean flag that becomes true once the page scrolls past a given pixel offset |
|
|
122
|
+
| `useInteractive` | hook | Scale state machine for hover and click interactions with configurable scale values |
|
|
123
|
+
| `usePerformanceMonitor` | hook | Measure real-time FPS via requestAnimationFrame and flag low-performance conditions |
|
|
124
|
+
| `useLanguageAwareMotion` | hook | Scroll-reveal animation that pauses or restarts when the active locale changes |
|
|
125
|
+
| `useGameLoop` | hook | Fixed-timestep requestAnimationFrame loop with FPS tracking, pause, and update/render callbacks |
|
|
126
|
+
| `useMotion` | hook | General-purpose from/to animation hook supporting fade, slide, scale, and rotate presets |
|
|
127
|
+
| `useViewportToggle` | hook | IntersectionObserver-based viewport enter/exit detection with once and trigger-mode options (absorbed from @hua-labs/pro; renamed from useVisibilityToggle to avoid collision) |
|
|
128
|
+
| `useScrollPositionToggle` | hook | Toggle visibility based on a window.pageYOffset threshold, with a scrollToTop helper (absorbed from @hua-labs/pro; renamed from useScrollToggle to avoid collision) |
|
|
129
|
+
| `neutral` | variable | Built-in neutral motion profile (minimal, system-respecting) |
|
|
130
|
+
| `hua` | variable | Built-in hua motion profile (expressive, brand-aligned) |
|
|
131
|
+
| `resolveProfile` | function | Resolve a built-in profile name or MotionProfile object to a MotionProfile |
|
|
132
|
+
| `mergeProfileOverrides` | function | Deep-merge overrides into a base MotionProfile |
|
|
133
|
+
| `MotionProfileProvider` | component | React context provider that supplies a MotionProfile to the subtree |
|
|
134
|
+
| `useMotionProfile` | hook | Hook to read the current MotionProfile from context |
|
|
135
|
+
| `observeElement` | function | Shared IntersectionObserver helper — observe an element and invoke a callback on visibility change |
|
|
136
|
+
| `linear` | function | Linear easing (no acceleration) |
|
|
137
|
+
| `easeIn` | function | Ease-in curve (slow start) |
|
|
138
|
+
| `easeOut` | function | Ease-out curve (slow end) |
|
|
139
|
+
| `easeInOut` | function | Smooth ease-in-out curve |
|
|
140
|
+
| `getEasing` | function | Get easing function by name |
|
|
141
|
+
| `applyEasing` | function | Apply an easing function to a raw progress value (throws on invalid) |
|
|
142
|
+
| `safeApplyEasing` | function | Apply an easing function to a progress value, falling back to linear on error |
|
|
143
|
+
| `isValidEasing` | function | Check whether a string is a recognised EasingType name |
|
|
144
|
+
| `getAvailableEasings` | function | Return the list of all registered easing names |
|
|
145
|
+
| `isEasingFunction` | function | Type-guard that checks whether a value is a callable EasingFunction |
|
|
146
|
+
| `easingPresets` | variable | Map of named easing preset strings to EasingFunction objects |
|
|
147
|
+
| `getPresetEasing` | function | Look up an EasingFunction by preset name |
|
|
148
|
+
| `calculateSpring` | function | Pure function that computes spring position/velocity for a given time step |
|
|
149
|
+
| `Motion` | component | React wrapper component that applies a motion hook to its child element via ref |
|
|
150
|
+
| `useCountUp` | hook | Animated counter that counts up to a target number |
|
|
151
|
+
| `useClipReveal` | hook | Clip-path reveal animation (wipe-in effect) |
|
|
152
|
+
| `useBlurIn` | hook | Blur-to-clear entrance animation |
|
|
153
|
+
| `useStagger` | hook | Orchestrate staggered entrance animations across a list of elements |
|
|
154
|
+
| `MOTION_PRESETS` | variable | Built-in preset configurations keyed by element role (hero, title, button, card, text, image) |
|
|
155
|
+
| `PAGE_MOTIONS` | variable | Page-level motion configs keyed by page type (home, dashboard, product, blog) |
|
|
156
|
+
| `mergeWithPreset` | function | Merge a MotionPreset with custom overrides |
|
|
157
|
+
| `getPagePreset` | function | Get PageMotionsConfig for a given PageType |
|
|
158
|
+
| `getMotionPreset` | function | Get a MotionPreset by element role string |
|
|
159
|
+
| `useFadeIn (native)` | hook | Native fade-in using Animated.timing |
|
|
160
|
+
| `useSlideUp (native)` | hook | Native slide-up using Animated.parallel |
|
|
161
|
+
| `useSlideDown (native)` | hook | Native slide-down using Animated.parallel |
|
|
162
|
+
| `useSlideLeft (native)` | hook | Native slide-left using Animated.parallel |
|
|
163
|
+
| `useSlideRight (native)` | hook | Native slide-right using Animated.parallel |
|
|
164
|
+
| `useScaleIn (native)` | hook | Native scale-in using Animated.parallel |
|
|
165
|
+
| `useBounceIn (native)` | hook | Native bounce-in using Animated.spring |
|
|
166
|
+
| `useSpringMotion (native)` | hook | Native generic spring animation with animateTo() |
|
|
167
|
+
| `usePulse (native)` | hook | Native looping pulse using Animated.loop |
|
|
168
|
+
| `useStagger (native)` | hook | Native staggered list animation using Animated.stagger |
|
|
80
169
|
|
|
81
170
|
## Documentation
|
|
82
171
|
|