@rootnative/inertia 0.0.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,507 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import * as react_native from 'react-native';
+import { NativeSyntheticEvent, NativeScrollEvent } from 'react-native';
+import { M as MotionComponent, T as TransitionConfig, A as AnimatableValue, E as EasingInput, S as SpringTransition, V as VariantController } from './types-cU43dEmH.mjs';
+export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, G as GestureSubStates, c as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, d as SequenceStep, e as TimingTransition, f as Transition, g as VariantsMap } from './types-cU43dEmH.mjs';
+import { SharedValue, useAnimatedStyle } from 'react-native-reanimated';
+export { U as UseGestureHandlers, a as UseGestureResult, u as useGesture } from './useGesture-DxtXdz-K.mjs';
+export { MotionImage } from './motion/Image.mjs';
+export { MotionPressable } from './motion/Pressable.mjs';
+export { MotionScrollView } from './motion/ScrollView.mjs';
+export { MotionText } from './motion/Text.mjs';
+export { MotionView } from './motion/View.mjs';
+
+/**
+ * Factory that wraps a React Native primitive as a `Motion.*` component.
+ *
+ * The generic `C` flows through `MotionProps`, so `animate` / `initial` /
+ * `exit` / `transition` all infer from `C`'s `style` prop. There is no
+ * shared `ViewStyle & TextStyle & ImageStyle` fallback.
+ *
+ * Alpha scope: numeric properties (transforms, opacity, width, height,
+ * borderRadius) and color properties (backgroundColor, borderColor, color,
+ * tintColor) applied via Reanimated shared values + `useAnimatedStyle`.
+ */
+declare function createMotionComponent<C extends ComponentType<any>>(Component: C): MotionComponent<C>;
+
+/**
+ * The `Motion.*` namespace. Each property is a primitive with its style prop
+ * inferred from the underlying RN component. There is no shared style fallback.
+ */
+declare const Motion: {
+    readonly View: MotionComponent<typeof react_native.View>;
+    readonly Text: MotionComponent<typeof react_native.Text>;
+    readonly Image: MotionComponent<typeof react_native.Image>;
+    readonly Pressable: MotionComponent<react.ForwardRefExoticComponent<react_native.PressableProps & react.RefAttributes<react_native.View>>>;
+    readonly ScrollView: MotionComponent<typeof react_native.ScrollView>;
+};
+
+/**
+ * How descendant Motion primitives should treat reduced-motion preferences.
+ *
+ * - `'user'` (default): defer to the OS accessibility setting via
+ *   Reanimated's `useReducedMotion()`. This is the only value that respects
+ *   user choice and is the right default for app-level wrappers.
+ * - `'never'`: animate regardless of OS setting. Use sparingly — e.g. for
+ *   onboarding transitions you've decided are essential.
+ * - `'always'`: never animate, regardless of OS setting. Useful for tests
+ *   and snapshots.
+ */
+type ReducedMotion = 'user' | 'never' | 'always';
+interface MotionConfigValue {
+    reducedMotion: ReducedMotion;
+}
+/**
+ * Read the active `<MotionConfig>` from a descendant. Returns the default
+ * (`'user'`) when no provider is present.
+ */
+declare function useMotionConfig(): MotionConfigValue;
+/**
+ * Resolve the active reduced-motion mode to a boolean. `'user'` consults
+ * Reanimated's OS-backed hook; `'always'` / `'never'` shortcut. Motion
+ * primitives call this to decide whether to swap transitions for
+ * `no-animation`.
+ */
+declare function useShouldReduceMotion(): boolean;
+
+/**
+ * Provider that controls how descendant Motion primitives respond to
+ * reduced-motion preferences. Wrap the root of your app once with the
+ * default (`reducedMotion="user"`) to respect the OS accessibility setting,
+ * or scope a subtree with `'always'` / `'never'` for specific use cases.
+ */
+declare function MotionConfig({ reducedMotion, children, }: {
+    reducedMotion?: ReducedMotion;
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * 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.
+ */
+declare function Presence({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * 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.
+ */
+interface PresenceContextValue {
+    isPresent: boolean;
+    safeToRemove: () => void;
+}
+/**
+ * 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.
+ */
+declare function usePresence(): PresenceContextValue | null;
+
+/**
+ * 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.
+ */
+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.
+ */
+type CallbackFactory = (phase: 'step' | 'animation', step: number | undefined) => AnimationCallback | undefined;
+/**
+ * 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.
+ */
+declare function resolveTransition(config: TransitionConfig | undefined, toValue: number | string, callback?: AnimationCallback): unknown;
+
+/**
+ * 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.
+ */
+declare function resolveAnimatableValue<V extends number | string>(value: AnimatableValue<V>, base: TransitionConfig | undefined, factory?: CallbackFactory): unknown;
+
+/**
+ * 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.
+ */
+declare function ensureWorkletEasing(easing: EasingInput | undefined): ((t: number) => number) | undefined;
+
+/**
+ * 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.
+ */
+declare function buildReleaseAnimation(transition: TransitionConfig, toValue: number): unknown;
+
+/**
+ * Drive a `SharedValue<number>` toward `target` with **any** transition shape
+ * — spring, timing, decay, or no-animation. The general-purpose value-layer
+ * hook: reach for it when you need raw `useSharedValue + useEffect + withX`
+ * outside the declarative `animate` flow.
+ *
+ * Re-runs whenever `target` changes shape (`target` is in the dep array) or
+ * the transition signature changes (kept stable via JSON-style hashing).
+ * Reduced motion (via `<MotionConfig reducedMotion>`) collapses the
+ * transition to `no-animation` so the value snaps instead of interpolating.
+ *
+ * **Spring shorthand.** Prefer [`useSpring`](./useSpring) when you only want
+ * spring physics — it accepts the same `tension`/`friction`/`mass` config and
+ * also supports a `SharedValue<number>` as the target (UI-thread reactive
+ * source). `useAnimation` is JS-thread-driven only.
+ *
+ * **Loops.** Repeat is part of `TransitionConfig` and flows through
+ * untouched — `useAnimation(1, { type: 'timing', duration: 1800, repeat: {
+ * count: 'infinite', alternate: false } })` produces an indeterminate-style
+ * progress driver.
+ *
+ * @example
+ * ```ts
+ * // Toggle progress (Switch / Checkbox / Radio).
+ * const progress = useAnimation(isChecked ? 1 : 0, {
+ *   type: 'spring',
+ *   tension: 380,
+ *   friction: 33,
+ * })
+ *
+ * // Float a TextField label when the value becomes non-empty.
+ * const floated = useAnimation(hasValue ? 1 : 0, {
+ *   type: 'timing',
+ *   duration: 150,
+ * })
+ *
+ * // Indeterminate progress slider (loops forever, snaps back).
+ * const slide = useAnimation(1, {
+ *   type: 'timing',
+ *   duration: 1800,
+ *   repeat: { count: 'infinite', alternate: false },
+ * })
+ * ```
+ */
+declare function useAnimation(target: number, transition?: TransitionConfig): SharedValue<number>;
+
+/**
+ * Toggle a 0↔1 progress value with a spring whenever `active` flips.
+ *
+ * This is the recurring shape behind checkbox checks, accordion expansions,
+ * drawer open/closed states, focus rings, and every other binary UI flip
+ * that wants spring physics rather than a hard cut. The returned shared
+ * value sits at `0` when `active` is `false` and animates toward `1` when
+ * `active` flips to `true` (and back again on the reverse flip). Feed it to
+ * a `useTransform`, `useShadow`, or a hand-rolled `useAnimatedStyle` to
+ * drive whatever the boolean controls visually.
+ *
+ * ```tsx
+ * const progress = useBooleanSpring(isChecked)
+ * const indicatorStyle = useAnimatedStyle(() => ({
+ *   opacity: progress.value,
+ *   transform: [{ scale: progress.value }],
+ * }))
+ * ```
+ *
+ * The spring config follows the same react-spring vocabulary as the rest of
+ * the library (`tension` / `friction` / `mass`); omit it to take the
+ * library's defaults.
+ */
+declare function useBooleanSpring(active: boolean, springConfig?: SpringTransition): SharedValue<number>;
+
+/**
+ * Color style keys understood by React Native that this hook can target.
+ * Sticks to the keys that exist on the v0.1 animatable surface so the
+ * returned style fragment is always a legal RN style.
+ */
+type ColorStyleKey = 'backgroundColor' | 'color' | 'borderColor' | 'borderTopColor' | 'borderRightColor' | 'borderBottomColor' | 'borderLeftColor' | 'tintColor' | 'shadowColor';
+interface UseColorTransitionOptions {
+    /**
+     * Which style slot the interpolated color is emitted under. Defaults to
+     * `backgroundColor` — the dominant case for state-layer haloes, card
+     * fills, and chip surfaces. Override for ring colors (`borderColor`),
+     * text colors (`color`), image tints (`tintColor`), etc.
+     */
+    key?: ColorStyleKey;
+}
+/**
+ * Interpolate a single color channel between `from` and `to` as `progress`
+ * moves 0→1, returning an animated style fragment that can be spread onto
+ * any Reanimated-aware view.
+ *
+ * ```tsx
+ * const progress = useBooleanSpring(isPressed)
+ * const fillStyle = useColorTransition(progress, [colors.surface, colors.pressed])
+ * const ringStyle = useColorTransition(progress, [colors.outline, colors.primary], {
+ *   key: 'borderColor',
+ * })
+ *
+ * return <Motion.View style={[styles.chip, fillStyle, ringStyle]} />
+ * ```
+ *
+ * This is a pure interpolator: it does not animate on its own. Drive
+ * `progress` upstream with a `useSpring`, `useBooleanSpring`, gesture
+ * progress, or scroll-derived `useTransform`. Values outside `[0, 1]`
+ * clamp. For a raw `SharedValue<string>` (e.g. to feed a gradient or
+ * compose into a hand-rolled `useAnimatedStyle`), use `useTransform`
+ * directly with a color output range.
+ */
+declare function useColorTransition(progress: SharedValue<number>, range: readonly [string, string], options?: UseColorTransitionOptions): ReturnType<typeof useAnimatedStyle>;
+
+/**
+ * Create an animatable value owned by JS but readable from worklets.
+ *
+ * This is the escape-hatch primitive that the rest of the value-layer hooks
+ * (`useSpring`, `useTransform`, `useScroll`) compose against. It is a thin
+ * pass-through over Reanimated's `useSharedValue`: a `SharedValue<T>` with
+ * `.value` for direct reads/writes (UI-thread reads in worklets, JS-thread
+ * writes from event handlers / effects).
+ *
+ * We intentionally do not introduce a `MotionValue` wrapper class around the
+ * shared value. The simplest object that interops with `useAnimatedStyle`,
+ * `useDerivedValue`, and every other Reanimated API _is_ the shared value
+ * itself; adding a `{ get, set, value }` shell would force consumers to
+ * unwrap it at every Reanimated boundary and break worklet capture.
+ *
+ * Worklet read:
+ * ```ts
+ * const x = useMotionValue(0)
+ * useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }))
+ * ```
+ *
+ * JS write:
+ * ```ts
+ * onPress={() => { x.value = 100 }}
+ * ```
+ */
+declare function useMotionValue<T extends number | string>(initial: T): SharedValue<T>;
+
+/**
+ * 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.
+ */
+declare function useSpring(target: number | SharedValue<number>, config?: SpringTransition): SharedValue<number>;
+
+/**
+ * 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.
+ */
+type ExtrapolationMode = 'clamp' | 'identity' | 'extend';
+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.
+ */
+declare 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.
+ */
+declare function useTransform(value: SharedValue<number>, inputRange: readonly number[], outputRange: readonly number[], options?: UseTransformOptions): SharedValue<number>;
+declare function useTransform(value: SharedValue<number>, inputRange: readonly number[], outputRange: readonly string[], options?: UseTransformOptions): SharedValue<string>;
+
+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.
+ */
+declare function useScroll(): UseScrollResult;
+
+/**
+ * Shape accepted on either end of a `useShadow` tween. Every field is
+ * optional — only keys present on at least one side participate in the
+ * output style. Mirrors the flat shadow keys on `Motion.View`'s `animate`
+ * surface, plus the nested `shadowOffset` source.
+ */
+interface ShadowConfig {
+    shadowOpacity?: number;
+    shadowRadius?: number;
+    shadowOffset?: {
+        width?: number;
+        height?: number;
+    };
+    /** Android elevation. iOS shadow consumers can leave this off. */
+    elevation?: number;
+    shadowColor?: string;
+}
+interface UseShadowOptions {
+    /** Shadow state at `progress === 0`. */
+    from: ShadowConfig;
+    /** Shadow state at `progress === 1`. */
+    to: ShadowConfig;
+    /**
+     * Driver — typically 0→1. Whatever produces it (a `useSpring`, a gesture
+     * progress value, a scroll-derived `useTransform`) is the caller's
+     * concern. The hook is a pure interpolator; it does not animate on its
+     * own. Values outside `[0, 1]` clamp.
+     */
+    progress: SharedValue<number>;
+}
+/**
+ * Interpolate between two shadow configs as `progress` moves 0→1, returning
+ * an animated style fragment that can be spread onto any Reanimated-aware
+ * view (including `Motion.*` primitives and a hand-rolled `Animated.View`).
+ *
+ * ```tsx
+ * const progress = useSpring(isElevated ? 1 : 0)
+ * const shadowStyle = useShadow({
+ *   from: { shadowOpacity: 0.08, shadowRadius: 2, shadowOffset: { width: 0, height: 1 }, elevation: 1 },
+ *   to:   { shadowOpacity: 0.24, shadowRadius: 12, shadowOffset: { width: 0, height: 8 }, elevation: 8 },
+ *   progress,
+ * })
+ *
+ * return <Motion.View style={[styles.card, shadowStyle]} />
+ * ```
+ *
+ * Only keys present on either `from` or `to` are emitted. A key present on
+ * one side and absent on the other tweens from the present value to the
+ * absent side's natural zero (`0` for numbers, `'transparent'` for
+ * `shadowColor`, `{ width: 0, height: 0 }` for `shadowOffset`). This is a
+ * pure interpolator — to "animate" the shadow, drive `progress` with a
+ * spring, timing, or gesture upstream.
+ */
+declare function useShadow({ from, to, progress, }: UseShadowOptions): ReturnType<typeof useAnimatedStyle>;
+
+/**
+ * Build a controller for a variants map. The controller is the imperative
+ * escape hatch — pass it to a Motion primitive via `controller={...}` and
+ * call `controller.transitionTo('open')` from event handlers, async chains,
+ * etc. The hook name mirrors the prop name (`variants`) so the relationship
+ * is obvious.
+ *
+ * The controller is identity-stable across renders. State changes are
+ * delivered to subscribers via `subscribe` — Motion primitives subscribe
+ * internally and re-resolve `animate` on each transition.
+ */
+declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
+
+export { AnimatableValue, type ColorStyleKey, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigValue, Presence, type PresenceContextValue, type ReducedMotion, type ShadowConfig, SpringTransition, TransitionConfig, type UseColorTransitionOptions, type UseScrollResult, type UseShadowOptions, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, ensureWorkletEasing, resolveAnimatableValue, resolveTransition, useAnimation, useBooleanSpring, useColorTransition, useMotionConfig, useMotionValue, usePresence, useScroll, useShadow, useShouldReduceMotion, useSpring, useTransform, useVariants };