[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/RN_Reanimated_3_Patterns.md

@@ -0,0 +1,191 @@
+---
+id: rn-reanimated-3-patterns
+title: Reanimated 3 — Worklet / shared value / 60fps
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [react-native, reanimated, animation, vibe-coding]
+tech_stack: { language: "TS / React Native", applicable_to: ["React Native"] }
+applied_in: []
+aliases: [Reanimated 3, useSharedValue, useAnimatedStyle, worklet, runOnJS]
+---
+
+# Reanimated 3
+
+> RN 의 60fps animation 표준. **JS thread 안 거치는 worklet**. shared value + animated style. Gesture Handler 와 페어. v3 = 자동 worklet (babel plugin).
+
+## 📖 핵심 개념
+- Worklet: UI thread 에서 실행되는 JS 함수 (반응형).
+- Shared value: worklet ↔ JS 양쪽에서 read/write.
+- Derived value: shared value → 계산.
+- runOnJS / runOnUI: thread 간 호출.
+
+## 💻 코드 패턴
+
+### Setup
+```bash
+yarn add react-native-reanimated
+# babel.config.js: 'react-native-reanimated/plugin' 추가 (마지막)
+```
+
+### Basic
+```tsx
+import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
+
+function Box() {
+  const offset = useSharedValue(0);
+
+  const style = useAnimatedStyle(() => ({
+    transform: [{ translateX: offset.value }],
+  }));
+
+  return (
+    <>
+      <Animated.View style={[styles.box, style]} />
+      <Button onPress={() => { offset.value = withSpring(offset.value + 100); }} />
+    </>
+  );
+}
+```
+
+### Gesture (with Gesture Handler 2)
+```tsx
+import { GestureDetector, Gesture } from 'react-native-gesture-handler';
+import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
+
+function Draggable() {
+  const x = useSharedValue(0);
+  const y = useSharedValue(0);
+
+  const pan = Gesture.Pan()
+    .onChange((e) => {
+      x.value += e.changeX;
+      y.value += e.changeY;
+    })
+    .onEnd(() => {
+      x.value = withSpring(0);
+      y.value = withSpring(0);
+    });
+
+  const style = useAnimatedStyle(() => ({
+    transform: [{ translateX: x.value }, { translateY: y.value }],
+  }));
+
+  return (
+    <GestureDetector gesture={pan}>
+      <Animated.View style={[styles.box, style]} />
+    </GestureDetector>
+  );
+}
+```
+
+### Derived value
+```tsx
+const progress = useSharedValue(0);
+const opacity = useDerivedValue(() => Math.min(progress.value / 100, 1));
+const scale = useDerivedValue(() => 1 + progress.value * 0.005);
+
+const style = useAnimatedStyle(() => ({
+  opacity: opacity.value,
+  transform: [{ scale: scale.value }],
+}));
+```
+
+### Scroll-driven
+```tsx
+import Animated, { useAnimatedScrollHandler, useSharedValue, useAnimatedStyle, interpolate } from 'react-native-reanimated';
+
+const scrollY = useSharedValue(0);
+const onScroll = useAnimatedScrollHandler({ onScroll: (e) => { scrollY.value = e.contentOffset.y; } });
+
+const headerStyle = useAnimatedStyle(() => ({
+  height: interpolate(scrollY.value, [0, 200], [120, 60], 'clamp'),
+}));
+
+return (
+  <>
+    <Animated.View style={[styles.header, headerStyle]} />
+    <Animated.ScrollView onScroll={onScroll} scrollEventThrottle={16}>...</Animated.ScrollView>
+  </>
+);
+```
+
+### runOnJS (UI → JS thread)
+```tsx
+const pan = Gesture.Pan().onEnd(() => {
+  if (x.value > 200) {
+    runOnJS(navigation.goBack)();
+  }
+});
+```
+
+### Layout animations
+```tsx
+import Animated, { FadeIn, FadeOut, SlideInRight } from 'react-native-reanimated';
+
+<Animated.View entering={FadeIn} exiting={FadeOut}>...</Animated.View>
+<Animated.View entering={SlideInRight.duration(300)}>...</Animated.View>
+```
+
+### Shared element (v3 experimental)
+```tsx
+<Animated.View sharedTransitionTag="hero">...</Animated.View>
+```
+
+### withSpring / withTiming / withDecay
+```ts
+offset.value = withSpring(100, { damping: 12, stiffness: 100 });
+offset.value = withTiming(100, { duration: 300, easing: Easing.out(Easing.cubic) });
+offset.value = withDecay({ velocity: 500, deceleration: 0.998 });
+```
+
+### Sequence / parallel
+```ts
+import { withSequence, withDelay, withRepeat } from 'react-native-reanimated';
+
+x.value = withSequence(
+  withTiming(100, { duration: 200 }),
+  withTiming(0, { duration: 200 }),
+);
+
+scale.value = withRepeat(withTiming(1.1, { duration: 500 }), -1, true); // 무한 yoyo
+```
+
+### Callback (animation 끝)
+```ts
+offset.value = withSpring(100, {}, (finished) => {
+  if (finished) runOnJS(onSettled)();
+});
+```
+
+## 🤔 의사결정 기준
+| 상황 | 추천 |
+|---|---|
+| 60fps 인터랙션 | Reanimated worklet |
+| 단순 enter/exit | Animated.timing 또는 LayoutAnimation |
+| 제스처 | Gesture Handler 2 + Reanimated |
+| 차트 / SVG | react-native-svg + Reanimated |
+| 3D / 게임 | Skia + Reanimated |
+| 단순 transition | css-style (Animated API 옛것) |
+
+## ❌ 안티패턴
+- **JS state 로 60fps animation**: jank.
+- **Worklet 안 외부 변수 (closure)**: dependency 명시 필요.
+- **runOnJS 매 frame**: 의미 없음. shared value.
+- **Worklet 안 async**: 안 됨. JS 로 보내기.
+- **Babel plugin 누락**: build 깨짐.
+- **scrollEventThrottle 누락 / 큼**: scroll animation 끊김.
+- **shared value 의 .value 를 worklet 외부에서 매 렌더 read**: re-render. useDerivedValue 또는 useAnimatedStyle.
+
+## 🤖 LLM 활용 힌트
+- v3 자동 worklet (babel) — 함수 안 쓰면 ` 'worklet';` 명시.
+- Gesture Handler 2 + Reanimated 가 표준.
+- runOnJS 는 마지막에만.
+
+## 🔗 관련 문서
+- [[React_Animation_Performance]]
+- [[RN_Hermes_Optimization]]
+- [[React_Native_Bridge_Performance]]