@rootnative/inertia 0.0.0-alpha.0

package/src/transitions/easing.ts

@@ -0,0 +1,53 @@
+// `isWorkletFunction` lives in `react-native-worklets` (the Reanimated 4 peer
+// dep); Reanimated's own re-export is deprecated.
+import { isWorkletFunction } from 'react-native-worklets'
+import { type EasingInput } from '../types'
+
+/**
+ * Reanimated 3.9+ validates that easing functions used in nested-transition
+ * contexts (variants, sequences, per-property maps) are worklets, and crashes
+ * with `[Reanimated] The easing function is not a worklet` otherwise. The
+ * library accepts plain functions on the public surface; this helper wraps
+ * them so consumers don't have to think about the worklet boundary.
+ *
+ * If the input is already a worklet (has been processed by the worklets babel
+ * plugin), it's returned as-is. Otherwise it's wrapped in a function whose
+ * body declares the `'worklet'` directive — when our source is processed by
+ * the consumer's worklets babel plugin (the default Expo/RN setup), the
+ * wrapper becomes a real worklet that captures the user fn via closure.
+ *
+ * Reanimated 4 changed `Easing.bezier(...)` to return an
+ * `EasingFunctionFactory` (`{ factory: () => EasingFunction }`) rather than
+ * the function itself. The helper accepts both shapes — `EasingFunction` and
+ * `EasingFunctionFactory` — and unwraps the factory automatically so
+ * consumers don't have to call `.factory()` manually.
+ *
+ * The user fn must be pure: no JS-thread captured refs, no shared mutable
+ * state, no calls to non-worklet APIs.
+ */
+export function ensureWorkletEasing(
+  easing: EasingInput | undefined,
+): ((t: number) => number) | undefined {
+  if (!easing) return undefined
+  // Reanimated 4 `EasingFunctionFactory` — unwrap via `.factory()` before
+  // checking worklet status, so the wrapped fn (not the factory wrapper)
+  // ends up in the transition config.
+  const fn = isEasingFactory(easing) ? easing.factory() : easing
+  if (isWorkletFunction(fn)) return fn
+  const wrapped = (t: number) => {
+    'worklet'
+    return fn(t)
+  }
+  return wrapped
+}
+
+function isEasingFactory(
+  value: EasingInput,
+): value is { factory: () => (t: number) => number } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'factory' in value &&
+    typeof (value as { factory: unknown }).factory === 'function'
+  )
+}

package/src/transitions/index.ts

@@ -0,0 +1,7 @@
+export { resolveTransition } from './resolve'
+export { resolveAnimatableValue } from './resolveSequence'
+export { ensureWorkletEasing } from './easing'
+export { isTopLevelTransition, TRANSITION_CONFIG_KEYS } from './keys'
+export { buildReleaseAnimation } from './runtime'
+export { stableSig } from './sig'
+export { DEFAULT_SPRING, springToReanimated } from './spring'

package/src/transitions/keys.ts

@@ -0,0 +1,32 @@
+import { type TransitionConfig } from '../types'
+
+/**
+ * Field names that may appear on a `TransitionConfig` (spring / timing /
+ * decay / no-animation). Used as a structural discriminator: if every key on
+ * an object is in this set, the object is treated as a top-level transition;
+ * otherwise it's a per-property / per-layer transition map.
+ *
+ * Adding a new field to `TransitionConfig` requires adding the name here.
+ */
+export const TRANSITION_CONFIG_KEYS = new Set([
+  'type',
+  'tension',
+  'friction',
+  'mass',
+  'velocity',
+  'restSpeedThreshold',
+  'restDisplacementThreshold',
+  'duration',
+  'easing',
+  'delay',
+  'repeat',
+  'deceleration',
+  'clamp',
+])
+
+export function isTopLevelTransition(t: unknown): t is TransitionConfig {
+  if (t === null || typeof t !== 'object') return false
+  const keys = Object.keys(t as object)
+  if (keys.length === 0) return false
+  return keys.every((k) => TRANSITION_CONFIG_KEYS.has(k))
+}

package/src/transitions/resolve.ts

@@ -0,0 +1,169 @@
+import {
+  Easing,
+  withDecay,
+  withDelay,
+  withRepeat,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated'
+import { ensureWorkletEasing } from './easing'
+import { springToReanimated } from './spring'
+import {
+  type DecayTransition,
+  type RepeatConfig,
+  type SpringTransition,
+  type TimingTransition,
+  type TransitionConfig,
+} from '../types'
+
+/**
+ * UI-thread callback Reanimated invokes when an animation settles. Must be a
+ * worklet — callers either author one with `'worklet'` or build one via
+ * `runOnJS(...)` to bridge to JS-thread code.
+ */
+export type AnimationCallback = (
+  finished?: boolean,
+  current?: number | string,
+) => void
+
+/**
+ * Per-step callback factory. Resolvers call this with the step's phase and
+ * sequence index (or `undefined` for non-sequence animations) and attach the
+ * resulting callback to the underlying `withSpring` / `withTiming` /
+ * `withDecay` call.
+ */
+export type CallbackFactory = (
+  phase: 'step' | 'animation',
+  step: number | undefined,
+) => AnimationCallback | undefined
+
+const DEFAULT_TIMING_DURATION = 250
+
+function buildSpring(
+  cfg: SpringTransition,
+  toValue: number | string,
+  cb?: AnimationCallback,
+) {
+  return withSpring(toValue as number, springToReanimated(cfg), cb as never)
+}
+
+function buildTiming(
+  cfg: TimingTransition,
+  toValue: number | string,
+  cb?: AnimationCallback,
+) {
+  return withTiming(
+    toValue as number,
+    {
+      duration: cfg.duration ?? DEFAULT_TIMING_DURATION,
+      easing: ensureWorkletEasing(cfg.easing) ?? Easing.inOut(Easing.ease),
+    },
+    cb as never,
+  )
+}
+
+function buildDecay(cfg: DecayTransition, cb?: AnimationCallback) {
+  return withDecay(
+    {
+      velocity: cfg.velocity ?? 0,
+      deceleration: cfg.deceleration,
+      clamp: cfg.clamp,
+    },
+    cb as never,
+  )
+}
+
+/**
+ * Build a single-step animation (no repeat / no delay / no sequence) for a
+ * given config + target. Pulled out so sequence steps can compose without
+ * recursing into repeat/delay handling per step. The callback is forwarded
+ * to Reanimated; for `no-animation` the callback is fired synchronously
+ * since there's nothing to wait for.
+ */
+function buildOne(
+  cfg: TransitionConfig,
+  toValue: number | string,
+  cb?: AnimationCallback,
+): unknown {
+  if (cfg.type === 'no-animation') {
+    if (cb) cb(true, toValue)
+    return toValue
+  }
+  if (cfg.type === 'decay') return buildDecay(cfg, cb)
+  if (cfg.type === 'timing') return buildTiming(cfg, toValue, cb)
+  return buildSpring(cfg as SpringTransition, toValue, cb)
+}
+
+/**
+ * Wrap an animation in `withRepeat` per the unified `repeat` shape:
+ *   - `number`              → finite count, alternating direction
+ *   - `'infinite'`          → endless, alternating direction
+ *   - `{ count, alternate }`→ explicit; `alternate` defaults to `true`
+ */
+export function applyRepeat(
+  animation: unknown,
+  repeat: RepeatConfig | undefined,
+) {
+  if (repeat === undefined) return animation
+  if (repeat === 'infinite') {
+    return withRepeat(animation as never, -1, true)
+  }
+  if (typeof repeat === 'number') {
+    return withRepeat(animation as never, repeat, true)
+  }
+  const count = repeat.count === 'infinite' ? -1 : repeat.count
+  const alternate = repeat.alternate ?? true
+  return withRepeat(animation as never, count, alternate)
+}
+
+function applyDelay(animation: unknown, delay: number | undefined) {
+  if (!delay || delay <= 0) return animation
+  return withDelay(delay, animation as never)
+}
+
+/**
+ * Build a Reanimated animation for a single property. Runs on the JS thread
+ * once per change and produces a baked `withSpring` / `withTiming` /
+ * `withDecay` (optionally wrapped in `withDelay` / `withRepeat`) call. The
+ * worklet body only consumes the result.
+ *
+ * `callback`, when provided, fires once when the underlying single-shot
+ * animation settles. Repeat-wrapped animations forward the callback to
+ * `withRepeat`, so it fires once per iteration as Reanimated does.
+ */
+export function resolveTransition(
+  config: TransitionConfig | undefined,
+  toValue: number | string,
+  callback?: AnimationCallback,
+): unknown {
+  const cfg = config ?? ({ type: 'spring' } as SpringTransition)
+  const base = buildOne(cfg, toValue, callback)
+  const repeated = applyRepeat(base, repeatOf(cfg))
+  return applyDelay(repeated, delayOf(cfg))
+}
+
+export function repeatOf(cfg: TransitionConfig): RepeatConfig | undefined {
+  if (cfg.type === 'no-animation' || cfg.type === 'decay') return undefined
+  return cfg.repeat
+}
+
+/**
+ * Return `cfg` minus its `repeat` field. Used when peeling top-level repeat
+ * off a base transition before passing it down to per-sequence-step
+ * resolution — the sequence as a whole is what should repeat, not each step.
+ */
+export function stripRepeat(
+  cfg: TransitionConfig | undefined,
+): TransitionConfig | undefined {
+  if (!cfg) return cfg
+  if (cfg.type === 'no-animation' || cfg.type === 'decay') return cfg
+  if (cfg.repeat === undefined) return cfg
+  const next = { ...cfg }
+  delete next.repeat
+  return next
+}
+
+function delayOf(cfg: TransitionConfig): number | undefined {
+  if (cfg.type === 'no-animation') return undefined
+  return cfg.delay
+}

package/src/transitions/resolveSequence.ts

@@ -0,0 +1,87 @@
+import { withSequence } from 'react-native-reanimated'
+import {
+  applyRepeat,
+  repeatOf,
+  resolveTransition,
+  stripRepeat,
+  type AnimationCallback,
+  type CallbackFactory,
+} from './resolve'
+import {
+  type AnimatableValue,
+  type SequenceStep,
+  type TransitionConfig,
+} from '../types'
+
+/**
+ * True when the value is a `{ to, ...transitionOverride }` sequence step.
+ * Plain numbers and plain transition objects fail this check.
+ */
+function isStepObject<V>(
+  v: SequenceStep<V> | V,
+): v is Extract<SequenceStep<V>, { to: V }> {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    !Array.isArray(v) &&
+    'to' in (v as object)
+  )
+}
+
+/**
+ * Resolve a per-property `animate` value into a Reanimated animation.
+ *
+ * Handles the three shapes of `AnimatableValue`:
+ *   1. plain value      → single `resolveTransition` call
+ *   2. `{ to, ...over }` → single step with the override merged into `base`
+ *   3. array of either   → `withSequence` of resolved steps, with the
+ *      top-level `repeat` applied at the **sequence level** (not per step).
+ *      Per-step `repeat` overrides remain step-local.
+ */
+export function resolveAnimatableValue<V extends number | string>(
+  value: AnimatableValue<V>,
+  base: TransitionConfig | undefined,
+  factory?: CallbackFactory,
+): unknown {
+  if (Array.isArray(value)) {
+    const steps = value as ReadonlyArray<SequenceStep<V>>
+    const stepBase = stripRepeat(base)
+    const animations = steps.map((step, i) =>
+      resolveStep(step, stepBase, factory?.('step', i)),
+    )
+    const seq = withSequence(...(animations as never[]))
+    return applyRepeat(seq, base ? repeatOf(base) : undefined)
+  }
+  const step = value as SequenceStep<V>
+  const cb = factory?.('animation', undefined)
+  if (isStepObject<V>(step)) {
+    return resolveStep(step, base, cb)
+  }
+  return resolveTransition(base, step as V, cb)
+}
+
+function resolveStep<V extends number | string>(
+  step: SequenceStep<V>,
+  base: TransitionConfig | undefined,
+  cb?: AnimationCallback,
+): unknown {
+  if (isStepObject<V>(step)) {
+    const { to, ...override } = step as { to: V } & Partial<TransitionConfig>
+    const merged = mergeTransition(base, override as Partial<TransitionConfig>)
+    return resolveTransition(merged, to, cb)
+  }
+  return resolveTransition(base, step as V, cb)
+}
+
+function mergeTransition(
+  base: TransitionConfig | undefined,
+  override: Partial<TransitionConfig>,
+): TransitionConfig {
+  // If the override declares a `type`, it wins outright — mixing fields from
+  // a spring base into a timing override produces garbage. Otherwise inherit
+  // the base's type and shallow-merge the rest.
+  if (override.type && base && override.type !== base.type) {
+    return override as TransitionConfig
+  }
+  return { ...(base ?? { type: 'spring' }), ...override } as TransitionConfig
+}

package/src/transitions/runtime.ts

@@ -0,0 +1,63 @@
+import {
+  Easing,
+  withDecay,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated'
+import { springToReanimated } from './spring'
+import { type TransitionConfig } from '../types'
+
+const DEFAULT_TIMING_DURATION = 250
+
+/**
+ * Worklet-safe single-step animation builder. Mirrors a subset of
+ * `resolveTransition` for the UI-thread path where the transition config is
+ * picked at gesture-release time, not at render time.
+ *
+ * Supported: spring / timing / decay / no-animation, single-step only.
+ * Not supported: sequences, top-level repeat, easing-function
+ * auto-worklet-wrapping (pass an already-worklet easing if you need a custom
+ * one — most release transitions don't).
+ *
+ * Use this from gesture worklets (`useDrag` / `usePan` release callbacks, or
+ * any custom `Gesture.Pan().onEnd(() => ...)` worklet) to animate a shared
+ * value with an Inertia transition without the JS round-trip that would lose
+ * the release velocity.
+ *
+ * For decay transitions, `toValue` is ignored — decay decelerates from the
+ * SV's current position via its own physics. Pass `0` if you don't have one.
+ */
+export function buildReleaseAnimation(
+  transition: TransitionConfig,
+  toValue: number,
+): unknown {
+  'worklet'
+  if (transition.type === 'no-animation') return toValue
+  if (transition.type === 'decay') {
+    const cfg: {
+      velocity: number
+      deceleration?: number
+      clamp?: [number, number]
+    } = { velocity: transition.velocity ?? 0 }
+    if (transition.deceleration !== undefined) {
+      cfg.deceleration = transition.deceleration
+    }
+    if (transition.clamp !== undefined) cfg.clamp = transition.clamp
+    return withDecay(cfg)
+  }
+  if (transition.type === 'timing') {
+    // Reanimated 4's `Easing.bezier(...)` returns an `EasingFunctionFactory`
+    // rather than the function itself. Unwrap inline so consumers calling
+    // `buildReleaseAnimation` from a gesture worklet don't have to.
+    const e = transition.easing
+    const easingFn =
+      e && typeof e === 'object' && 'factory' in e
+        ? e.factory()
+        : (e ?? Easing.inOut(Easing.ease))
+    return withTiming(toValue, {
+      duration: transition.duration ?? DEFAULT_TIMING_DURATION,
+      easing: easingFn,
+    })
+  }
+  return withSpring(toValue, springToReanimated(transition))
+}

package/src/transitions/sig.ts

@@ -0,0 +1,40 @@
+/**
+ * Stable string signature for an arbitrary value — used as a dep-array
+ * member so a fresh object literal each render doesn't re-fire an effect
+ * unless something structurally changed. Functions serialize as `null`
+ * (their identity isn't useful in a sig); `undefined` collapses to an empty
+ * string so omitted props compare equal across renders.
+ */
+export function stableSig(value: unknown): string {
+  if (value === undefined) return ''
+  try {
+    return stableStringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+/**
+ * JSON.stringify with keys sorted at every level so a sig is invariant under
+ * property-declaration order. Functions and `undefined` both serialize as
+ * `null` — we accept the latter's information loss (rare in practice) in
+ * exchange for not crashing on circular function-bearing graphs.
+ */
+function stableStringify(v: unknown): string {
+  if (v === null || typeof v !== 'object') {
+    if (typeof v === 'function' || v === undefined) return 'null'
+    return JSON.stringify(v)
+  }
+  if (Array.isArray(v)) {
+    return '[' + v.map(stableStringify).join(',') + ']'
+  }
+  const obj = v as Record<string, unknown>
+  const keys = Object.keys(obj).sort()
+  return (
+    '{' +
+    keys
+      .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
+      .join(',') +
+    '}'
+  )
+}

package/src/transitions/spring.ts

@@ -0,0 +1,42 @@
+import { type SpringTransition } from '../types'
+
+/**
+ * Default spring physics, expressed in react-spring vocabulary.
+ *
+ * `tension: 170` / `friction: 26` / `mass: 1` was picked over Reanimated's
+ * raw `stiffness: 100` / `damping: 10` default because the raw default
+ * overshoots noticeably for the small (~100px) translates that dominate
+ * UI work — buttons, sheets, popovers. These numbers settle in ~350ms with
+ * a single, almost-imperceptible overshoot, which matches the perceptual
+ * target the rest of the library is tuned against.
+ */
+export const DEFAULT_SPRING: Required<
+  Pick<SpringTransition, 'tension' | 'friction' | 'mass'>
+> = {
+  tension: 170,
+  friction: 26,
+  mass: 1,
+}
+
+/**
+ * Convert public react-spring vocabulary (`tension` / `friction` / `mass`)
+ * to Reanimated's raw `stiffness` / `damping` / `mass`. This is the single
+ * place the mapping lives; resolvers, value hooks, and any future surface
+ * that needs a Reanimated spring config import from here.
+ *
+ * The mapping is identity (tension ≡ stiffness, friction ≡ damping) — the
+ * names differ but the underlying physics constants are the same. We don't
+ * surface the raw names publicly because the react-spring vocabulary is
+ * what designers and prior-art consumers expect.
+ */
+export function springToReanimated(t: SpringTransition) {
+  'worklet'
+  return {
+    stiffness: t.tension ?? DEFAULT_SPRING.tension,
+    damping: t.friction ?? DEFAULT_SPRING.friction,
+    mass: t.mass ?? DEFAULT_SPRING.mass,
+    velocity: t.velocity,
+    restSpeedThreshold: t.restSpeedThreshold,
+    restDisplacementThreshold: t.restDisplacementThreshold,
+  }
+}