@onlynative/inertia 0.0.1-alpha.2 → 0.0.1-alpha.4

package/src/values/useScroll.ts

@@ -0,0 +1,72 @@
+import {
+  useAnimatedScrollHandler,
+  useSharedValue,
+  type SharedValue,
+} from 'react-native-reanimated'
+import { type NativeScrollEvent, type NativeSyntheticEvent } from 'react-native'
+
+export interface UseScrollResult {
+  /** Horizontal scroll offset in points. */
+  scrollX: SharedValue<number>
+  /** Vertical scroll offset in points. */
+  scrollY: SharedValue<number>
+  /**
+   * Handler to pass to a `Motion.ScrollView`'s `onScroll` prop (or any other
+   * Reanimated `Animated.ScrollView`). The handler is opaque to JS — it runs
+   * as a worklet — but the type narrows to the same shape RN's native
+   * `onScroll` prop expects so it composes cleanly.
+   */
+  onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void
+}
+
+/**
+ * Track the scroll offset of a `Motion.ScrollView` as shared values.
+ *
+ * ```tsx
+ * const { scrollY, onScroll } = useScroll()
+ * const headerOpacity = useTransform(scrollY, [0, 100], [1, 0])
+ *
+ * return (
+ *   <>
+ *     <Motion.View animate={{ opacity: headerOpacity }} />
+ *     <Motion.ScrollView onScroll={onScroll} scrollEventThrottle={16}>
+ *       …
+ *     </Motion.ScrollView>
+ *   </>
+ * )
+ * ```
+ *
+ * Scroll events fire on the UI thread, so `scrollX` / `scrollY` are safe to
+ * read from any worklet (`useAnimatedStyle`, `useDerivedValue`,
+ * `useTransform`) without a JS-thread bounce.
+ *
+ * Remember to set `scrollEventThrottle={16}` on the `ScrollView` for 60Hz
+ * updates — RN's default is to dispatch on every event, which on iOS still
+ * means one per frame, but Android benefits from the explicit cap.
+ */
+export function useScroll(): UseScrollResult {
+  const scrollX = useSharedValue(0)
+  const scrollY = useSharedValue(0)
+
+  const handler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      'worklet'
+      scrollX.value = event.contentOffset.x
+      scrollY.value = event.contentOffset.y
+    },
+  })
+
+  // `useAnimatedScrollHandler` returns an opaque worklet bag whose JS-side
+  // type is `(event) => void` but actually carries native event-handler
+  // wiring. Cast through `unknown` because the public RN `onScroll` type
+  // wants a `NativeSyntheticEvent`-taking function and Reanimated's handler
+  // is structurally compatible — the cast is to satisfy the consumer's
+  // prop type at the call site.
+  return {
+    scrollX,
+    scrollY,
+    onScroll: handler as unknown as (
+      event: NativeSyntheticEvent<NativeScrollEvent>,
+    ) => void,
+  }
+}

package/src/values/useSpring.ts

@@ -0,0 +1,93 @@
+import { useEffect, useMemo } from 'react'
+import {
+  useAnimatedReaction,
+  useSharedValue,
+  withSpring,
+  type SharedValue,
+} from 'react-native-reanimated'
+import { springToReanimated } from '../transitions/spring'
+import { type SpringTransition } from '../types'
+
+/**
+ * Animate a shared value toward `target` with spring physics, using the
+ * library's react-spring vocabulary (`tension` / `friction` / `mass`).
+ *
+ * `target` may be a plain number or a `SharedValue<number>`. The plain-number
+ * path drives the spring from a JS `useEffect`, so the animation re-runs on
+ * every render where `target` changes. The shared-value path drives the
+ * spring from a Reanimated reaction on the UI thread, so values produced by
+ * gestures, scroll handlers, or other worklets flow through without bouncing
+ * back to JS.
+ *
+ * Both call sites end up at the same `withSpring` invocation; the split is
+ * just about which thread observes the source change.
+ */
+export function useSpring(
+  target: number | SharedValue<number>,
+  config?: SpringTransition,
+): SharedValue<number> {
+  // Reanimated config is rebuilt only when the public config object changes
+  // shape. The worklet path reads this from JS-thread closure capture, which
+  // is fine: it's the resolved config that's invariant across UI-thread
+  // ticks, not a JS-thread reference that would go stale.
+  const reanimConfig = useMemo(
+    () => springToReanimated(config ?? {}),
+    [
+      config?.tension,
+      config?.friction,
+      config?.mass,
+      config?.velocity,
+      config?.restSpeedThreshold,
+      config?.restDisplacementThreshold,
+    ],
+  )
+
+  const isSharedTarget = isSharedValue(target)
+  const initial = isSharedTarget ? target.value : (target as number)
+  const output = useSharedValue<number>(initial)
+
+  // Plain-number path. The reaction below is a no-op when `target` is a
+  // number, so this effect carries the change. Reading `target` directly in
+  // the dep array means React drives the schedule; we don't have to babysit
+  // a stale closure.
+  useEffect(() => {
+    if (isSharedTarget) return
+    output.value = withSpring(target as number, reanimConfig)
+    // `output` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isSharedTarget, target, reanimConfig])
+
+  // SharedValue path. `useAnimatedReaction` runs the prepare worklet whenever
+  // its returned value changes; we read `.value` off the target SV and pipe
+  // it through `withSpring` on the UI thread. When the target is a plain
+  // number we never declare a source so the reaction is inert (returns
+  // `null`, never fires `react`).
+  useAnimatedReaction(
+    () => {
+      'worklet'
+      if (!isSharedTarget) return null
+      return (target as SharedValue<number>).value
+    },
+    (next, prev) => {
+      'worklet'
+      if (next === null || next === prev) return
+      output.value = withSpring(next, reanimConfig)
+    },
+    [isSharedTarget, reanimConfig],
+  )
+
+  return output
+}
+
+function isSharedValue(v: unknown): v is SharedValue<number> {
+  // SharedValues are plain objects with a single `value` accessor — there is
+  // no public constructor or instanceof check. Reading `'value' in v` on any
+  // POJO would also pass, but the hook's call site already narrows the type;
+  // this guard exists to dispatch between the two implementation paths, not
+  // to validate untrusted input.
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    'value' in (v as Record<string, unknown>)
+  )
+}

package/src/values/useTransform.ts

@@ -0,0 +1,132 @@
+import {
+  Extrapolation,
+  interpolate,
+  interpolateColor,
+  useDerivedValue,
+  type SharedValue,
+} from 'react-native-reanimated'
+// `isWorkletFunction` was re-exported from `react-native-reanimated` historically
+// but is deprecated there in favor of importing from `react-native-worklets`.
+// `react-native-worklets` is a required peer of Reanimated 4, so the direct
+// import is always available wherever Inertia is.
+import { isWorkletFunction } from 'react-native-worklets'
+
+/**
+ * Extrapolation behavior at the edges of the input range. Mirrors
+ * Reanimated's enum so consumers don't need a separate import.
+ *
+ * - `'clamp'` (default) — output stays pinned at the first/last value
+ *   outside the input range. Matches Framer Motion's default.
+ * - `'identity'` — return the input unchanged outside the range.
+ * - `'extend'` — continue the linear slope beyond the range.
+ */
+export type ExtrapolationMode = 'clamp' | 'identity' | 'extend'
+
+export interface UseTransformOptions {
+  extrapolateLeft?: ExtrapolationMode
+  extrapolateRight?: ExtrapolationMode
+}
+
+/**
+ * Derive a value from one or more shared values via a transformer worklet.
+ *
+ * ```ts
+ * const x = useMotionValue(0)
+ * const y = useMotionValue(0)
+ * const distance = useTransform(() => Math.sqrt(x.value ** 2 + y.value ** 2))
+ * ```
+ *
+ * The transformer must be a worklet (or a plain function we auto-wrap —
+ * see the easing wrapper for the rationale). It runs on the UI thread on
+ * every frame where any read shared value changes.
+ */
+export function useTransform<T>(transformer: () => T): SharedValue<T>
+
+/**
+ * Interpolate a numeric shared value onto a range of numbers or colors.
+ *
+ * ```ts
+ * const scroll = useMotionValue(0)
+ * const headerOpacity = useTransform(scroll, [0, 100], [1, 0])
+ * const headerColor  = useTransform(scroll, [0, 100], ['#fff', '#000'])
+ * ```
+ *
+ * When `outputRange` is numeric, this maps to Reanimated's `interpolate`;
+ * when it's a tuple of color strings, it maps to `interpolateColor`. The
+ * input range must be monotonically increasing.
+ */
+export function useTransform(
+  value: SharedValue<number>,
+  inputRange: readonly number[],
+  outputRange: readonly number[],
+  options?: UseTransformOptions,
+): SharedValue<number>
+export function useTransform(
+  value: SharedValue<number>,
+  inputRange: readonly number[],
+  outputRange: readonly string[],
+  options?: UseTransformOptions,
+): SharedValue<string>
+
+export function useTransform<T>(
+  arg1: (() => T) | SharedValue<number>,
+  inputRange?: readonly number[],
+  outputRange?: readonly number[] | readonly string[],
+  options?: UseTransformOptions,
+): SharedValue<T> | SharedValue<number> | SharedValue<string> {
+  // Build the producer worklet on the JS thread, then call
+  // `useDerivedValue` exactly once. Keeping the hook call unconditional
+  // satisfies rules-of-hooks; per-call branching (transformer vs
+  // interpolation) is decided once at JS time, never at frame time.
+  let producer: () => unknown
+  if (typeof arg1 === 'function') {
+    // Transformer overload. The public surface accepts a plain function;
+    // Reanimated 3.9+ requires worklets in nested-derivation contexts, so
+    // we auto-wrap at JS time the same way `ensureWorkletEasing` does.
+    const userFn = arg1 as () => T
+    producer = isWorkletFunction(userFn)
+      ? userFn
+      : () => {
+          'worklet'
+          return userFn()
+        }
+  } else {
+    // Interpolation overload. We pre-resolve everything JS-side so the
+    // worklet body only consumes flat values.
+    const source = arg1
+    const input = inputRange as readonly number[]
+    const output = outputRange as readonly (number | string)[]
+    const isColor = output.length > 0 && typeof output[0] === 'string'
+    const extrapolateLeft = mapExtrapolation(options?.extrapolateLeft)
+    const extrapolateRight = mapExtrapolation(options?.extrapolateRight)
+    producer = isColor
+      ? () => {
+          'worklet'
+          return interpolateColor(
+            source.value,
+            input as number[],
+            output as string[],
+          )
+        }
+      : () => {
+          'worklet'
+          return interpolate(
+            source.value,
+            input as number[],
+            output as number[],
+            { extrapolateLeft, extrapolateRight },
+          )
+        }
+  }
+
+  return useDerivedValue(producer as () => never) as unknown as
+    | SharedValue<T>
+    | SharedValue<number>
+    | SharedValue<string>
+}
+
+function mapExtrapolation(mode: ExtrapolationMode | undefined): Extrapolation {
+  if (mode === 'identity') return Extrapolation.IDENTITY
+  if (mode === 'extend') return Extrapolation.EXTEND
+  return Extrapolation.CLAMP
+}