@onlynative/inertia 0.0.1-alpha.0

package/src/motion/index.ts

@@ -0,0 +1,26 @@
+import { MotionImage } from './Image'
+import { MotionPressable } from './Pressable'
+import { MotionScrollView } from './ScrollView'
+import { MotionText } from './Text'
+import { MotionView } from './View'
+
+export { createMotionComponent } from './createMotionComponent'
+export {
+  MotionView,
+  MotionText,
+  MotionImage,
+  MotionPressable,
+  MotionScrollView,
+}
+
+/**
+ * The `Motion.*` namespace. Each property is a primitive with its style prop
+ * inferred from the underlying RN component. There is no shared style fallback.
+ */
+export const Motion = {
+  View: MotionView,
+  Text: MotionText,
+  Image: MotionImage,
+  Pressable: MotionPressable,
+  ScrollView: MotionScrollView,
+} as const

package/src/presence/Presence.tsx

@@ -0,0 +1,165 @@
+import {
+  Children,
+  isValidElement,
+  type Key,
+  type ReactElement,
+  type ReactNode,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import { PresenceContext, type PresenceContextValue } from './PresenceContext'
+
+interface RenderEntry {
+  key: Key
+  element: ReactElement
+  isPresent: boolean
+}
+
+/**
+ * Wrap a list of children with mount / unmount transitions. When a child is
+ * removed from the incoming list it stays in the snapshot until its exit
+ * animation completes; descendants consume the per-child `<PresenceContext>`
+ * to coordinate.
+ *
+ * Children must be `<Motion.*>` primitives (or any component that consumes
+ * `usePresence()` and calls `safeToRemove`). Plain elements without that
+ * contract will linger in the snapshot once removed; document that and pick
+ * the right primitive.
+ *
+ * Children also need explicit `key`s so removal is detectable across
+ * renders. Without a key, React falls back to positional identity and
+ * removal looks like a prop change — Presence has nothing to mark exiting.
+ */
+export function Presence({ children }: { children: ReactNode }) {
+  const incoming = useMemo(() => {
+    const out: ReactElement[] = []
+    Children.forEach(children, (child) => {
+      if (!isValidElement(child)) return
+      if (child.key === null) {
+        if (__DEV__) {
+          console.warn(
+            '[inertia] <Presence> children must have a `key`. Skipping a keyless child.',
+          )
+        }
+        return
+      }
+      out.push(child)
+    })
+    return out
+  }, [children])
+
+  // Snapshot of elements removed from `incoming` whose exit animation is
+  // still in flight. setExiting is called synchronously during render below
+  // (the documented pattern for derived-from-prop-change state), so React
+  // re-renders with the new snapshot before committing — no visual frame
+  // where the departing child has vanished.
+  const [exiting, setExiting] = useState<Map<Key, ReactElement>>(
+    () => new Map(),
+  )
+
+  // Tracks the previous render's `incoming` so we can diff. Updated
+  // synchronously alongside the setState call.
+  const prevIncomingRef = useRef<ReactElement[]>(incoming)
+
+  if (prevIncomingRef.current !== incoming) {
+    const prev = prevIncomingRef.current
+    prevIncomingRef.current = incoming
+    const incomingKeys = new Set(incoming.map((el) => el.key as Key))
+    let next: Map<Key, ReactElement> | null = null
+    const ensureMutable = () => {
+      if (!next) next = new Map(exiting)
+      return next
+    }
+
+    // Departures: in prev but not in current → snapshot for exit.
+    for (const oldEl of prev) {
+      const key = oldEl.key as Key
+      if (!incomingKeys.has(key) && !exiting.has(key)) {
+        ensureMutable().set(key, oldEl)
+      }
+    }
+    // Returns: was exiting and reappears → drop the snapshot. The live
+    // `incoming` entry takes over with the same key, so React reconciles
+    // the underlying Motion instance and the in-flight exit animation
+    // interrupts back toward `animate` values.
+    for (const el of incoming) {
+      const key = el.key as Key
+      if (exiting.has(key)) {
+        ensureMutable().delete(key)
+      }
+    }
+
+    if (next) setExiting(next)
+  }
+
+  const handleRemove = useCallback((key: Key) => {
+    setExiting((prev) => {
+      if (!prev.has(key)) return prev
+      const next = new Map(prev)
+      next.delete(key)
+      return next
+    })
+  }, [])
+
+  // Single combined render list. Putting `incoming` and `exiting` entries in
+  // one array (rather than two `.map` calls inside a fragment) ensures React
+  // reconciles by `key` across positions — when an entry moves from
+  // present-list to exiting-list, the component instance persists.
+  const renderList: RenderEntry[] = []
+  for (const el of incoming) {
+    renderList.push({
+      key: el.key as Key,
+      element: el,
+      isPresent: true,
+    })
+  }
+  for (const [key, el] of exiting) {
+    if (!renderList.some((entry) => entry.key === key)) {
+      renderList.push({ key, element: el, isPresent: false })
+    }
+  }
+
+  return (
+    <>
+      {renderList.map(({ key, element, isPresent }) => (
+        <PresenceItem
+          key={key}
+          itemKey={key}
+          isPresent={isPresent}
+          onRemove={handleRemove}
+        >
+          {element}
+        </PresenceItem>
+      ))}
+    </>
+  )
+}
+
+function PresenceItem({
+  itemKey,
+  isPresent,
+  onRemove,
+  children,
+}: {
+  itemKey: Key
+  isPresent: boolean
+  onRemove: (key: Key) => void
+  children: ReactNode
+}) {
+  const value = useMemo<PresenceContextValue>(
+    () => ({
+      isPresent,
+      safeToRemove: () => onRemove(itemKey),
+    }),
+    [isPresent, itemKey, onRemove],
+  )
+  return (
+    <PresenceContext.Provider value={value}>
+      {children}
+    </PresenceContext.Provider>
+  )
+}
+
+declare const __DEV__: boolean

package/src/presence/PresenceContext.ts

@@ -0,0 +1,28 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Per-child contract between `<Presence>` and its descendant Motion
+ * primitives. `<Presence>` provides a fresh value to each rendered child;
+ * Motion primitives consume it to gate exit animations.
+ *
+ * - `isPresent`: `true` while the child is in the incoming children list.
+ *   Flips to `false` when the parent removes it; the child remains rendered
+ *   until `safeToRemove` is called.
+ * - `safeToRemove`: callback the child invokes when its exit animation has
+ *   settled. `<Presence>` then drops the snapshot entry and unmounts.
+ */
+export interface PresenceContextValue {
+  isPresent: boolean
+  safeToRemove: () => void
+}
+
+export const PresenceContext = createContext<PresenceContextValue | null>(null)
+
+/**
+ * Read the surrounding `<Presence>` contract from a child component. Returns
+ * `null` when there is no `<Presence>` ancestor — useful for components that
+ * want to support both standalone and Presence-wrapped use without branching.
+ */
+export function usePresence(): PresenceContextValue | null {
+  return useContext(PresenceContext)
+}

package/src/presence/index.ts

@@ -0,0 +1,6 @@
+export { Presence } from './Presence'
+export {
+  PresenceContext,
+  usePresence,
+  type PresenceContextValue,
+} from './PresenceContext'

package/src/transitions/easing.ts

@@ -0,0 +1,29 @@
+import { isWorkletFunction } from 'react-native-reanimated'
+
+/**
+ * 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.
+ *
+ * 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: ((t: number) => number) | undefined,
+): ((t: number) => number) | undefined {
+  if (!easing) return undefined
+  if (isWorkletFunction(easing)) return easing
+  const wrapped = (t: number) => {
+    'worklet'
+    return easing(t)
+  }
+  return wrapped
+}

package/src/transitions/index.ts

@@ -0,0 +1,2 @@
+export { resolveTransition, resolveAnimatableValue } from './resolve'
+export { ensureWorkletEasing } from './easing'

package/src/transitions/resolve.ts

@@ -0,0 +1,265 @@
+import {
+  Easing,
+  withDecay,
+  withDelay,
+  withRepeat,
+  withSequence,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated'
+import { ensureWorkletEasing } from './easing'
+import {
+  type AnimatableValue,
+  type DecayTransition,
+  type RepeatConfig,
+  type SequenceStep,
+  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
+
+/**
+ * Default spring physics, expressed in react-spring vocabulary. Conversion
+ * to Reanimated's raw `stiffness` / `damping` lives below; raw config never
+ * leaks past this module.
+ */
+const DEFAULT_SPRING: Required<
+  Pick<SpringTransition, 'tension' | 'friction' | 'mass'>
+> = {
+  tension: 170,
+  friction: 26,
+  mass: 1,
+}
+
+const DEFAULT_TIMING_DURATION = 250
+
+function springToReanimated(t: SpringTransition) {
+  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,
+  }
+}
+
+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`
+ */
+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))
+}
+
+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.
+ */
+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
+}
+
+/**
+ * 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
+}