@onlynative/inertia 0.0.1-alpha.7 → 0.0.1-alpha.9

package/dist/index.d.mts

@@ -2,9 +2,10 @@ 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, A as AnimatableValue, T as TransitionConfig, E as EasingInput, G as GestureLayerTransitions, S as SpringTransition, V as VariantController } from './types-NmNeJjo1.mjs';
-export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, c as GestureSubStates, d as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, e as SequenceStep, f as TimingTransition, g as Transition, h as VariantsMap } from './types-NmNeJjo1.mjs';
-import { SharedValue } from 'react-native-reanimated';
+import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, 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-cimMrzC1.mjs';
 export { MotionImage } from './motion/Image.mjs';
 export { MotionPressable } from './motion/Pressable.mjs';
 export { MotionScrollView } from './motion/ScrollView.mjs';
@@ -243,84 +244,68 @@ declare function buildReleaseAnimation(transition: TransitionConfig, toValue: nu
 declare function useAnimation(target: number, transition?: TransitionConfig): SharedValue<number>;
 
 /**
- * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the
- * shared values returned alongside.
+ * Toggle a 0↔1 progress value with a spring whenever `active` flips.
  *
- * Hover handlers use `Pressable`'s own `onHoverIn` / `onHoverOut` names (web
- * only — no-ops on native). `onFocus` consults `isFocusVisible()` before
- * raising the keyboard-only `focusVisible` layer; `focused` always raises.
+ * 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.
  */
-interface UseGestureHandlers {
-    onPressIn: () => void;
-    onPressOut: () => void;
-    onHoverIn: () => void;
-    onHoverOut: () => void;
-    onFocus: () => void;
-    onBlur: () => void;
-}
-interface UseGestureResult {
-    /** 0↔1 progress for the pressed layer. */
-    pressed: SharedValue<number>;
-    /** 0↔1 progress for the focused layer (any focus modality). */
-    focused: SharedValue<number>;
-    /** 0↔1 progress for the focusVisible layer (keyboard focus only). */
-    focusVisible: SharedValue<number>;
-    /** 0↔1 progress for the hovered layer (web only — stays at 0 on native). */
-    hovered: SharedValue<number>;
-    /** Handlers to spread on the receiving `Pressable`. */
-    handlers: UseGestureHandlers;
+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;
 }
 /**
- * Build a gesture-layer controller. The hook-form of the `gesture` prop —
- * reach for it when you need to drive multiple animated views from the same
- * gesture state (a focus ring + state-layer halo + content tint all on one
- * Pressable), which the prop-form's "animate the receiver's own style" model
- * can't express.
- *
- * Returns four 0↔1 shared values (one per layer) and a handler bag to spread
- * on a `Pressable`. The shared values are stable across renders — feed them
- * into any number of `useAnimatedStyle` blocks anywhere in the tree.
- *
- * Transitions follow the same shape as the `gesture` prop's accompanying
- * `transition`: pass a single `TransitionConfig` to use for every layer, or a
- * `GestureLayerTransitions` map to give each layer its own. Layers without an
- * explicit transition fall back to the library default spring.
+ * 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.
  *
- * Reduced motion (via `<MotionConfig reducedMotion>`) collapses every
- * transition to `no-animation` so state changes snap instead of interpolating
- * — same behaviour the gesture prop applies.
- *
- * @example
  * ```tsx
- * import { useAnimatedStyle } from 'react-native-reanimated'
- * import { useGesture } from '@onlynative/inertia'
- *
- * function Card() {
- *   const { pressed, focused, hovered, handlers } = useGesture({
- *     pressed: { type: 'timing', duration: 100 },
- *     hovered: { type: 'timing', duration: 150 },
- *     focused: { type: 'timing', duration: 200 },
- *   })
- *
- *   const ringStyle = useAnimatedStyle(() => ({ opacity: focused.value }))
- *   const haloStyle = useAnimatedStyle(() => ({
- *     opacity: Math.max(
- *       hovered.value * 0.08,
- *       focused.value * 0.10,
- *       pressed.value * 0.10,
- *     ),
- *   }))
- *
- *   return (
- *     <Pressable {...handlers}>
- *       <Animated.View style={ringStyle} />
- *       <Animated.View style={haloStyle} />
- *     </Pressable>
- *   )
- * }
+ * 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 useGesture(transition?: TransitionConfig | GestureLayerTransitions): UseGestureResult;
+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.
@@ -450,6 +435,61 @@ interface UseScrollResult {
  */
 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
@@ -463,4 +503,4 @@ declare function useScroll(): UseScrollResult;
  */
 declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
 
-export { AnimatableValue, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigValue, Presence, type PresenceContextValue, type ReducedMotion, SpringTransition, TransitionConfig, type UseGestureHandlers, type UseGestureResult, type UseScrollResult, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, ensureWorkletEasing, resolveAnimatableValue, resolveTransition, useAnimation, useGesture, useMotionConfig, useMotionValue, usePresence, useScroll, useShouldReduceMotion, useSpring, useTransform, useVariants };
+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 };

package/dist/index.d.ts

@@ -2,9 +2,10 @@ 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, A as AnimatableValue, T as TransitionConfig, E as EasingInput, G as GestureLayerTransitions, S as SpringTransition, V as VariantController } from './types-NmNeJjo1.js';
-export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, c as GestureSubStates, d as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, e as SequenceStep, f as TimingTransition, g as Transition, h as VariantsMap } from './types-NmNeJjo1.js';
-import { SharedValue } from 'react-native-reanimated';
+import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, E as EasingInput, S as SpringTransition, V as VariantController } from './types-cU43dEmH.js';
+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.js';
+import { SharedValue, useAnimatedStyle } from 'react-native-reanimated';
+export { U as UseGestureHandlers, a as UseGestureResult, u as useGesture } from './useGesture-B7A_1DVg.js';
 export { MotionImage } from './motion/Image.js';
 export { MotionPressable } from './motion/Pressable.js';
 export { MotionScrollView } from './motion/ScrollView.js';
@@ -243,84 +244,68 @@ declare function buildReleaseAnimation(transition: TransitionConfig, toValue: nu
 declare function useAnimation(target: number, transition?: TransitionConfig): SharedValue<number>;
 
 /**
- * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the
- * shared values returned alongside.
+ * Toggle a 0↔1 progress value with a spring whenever `active` flips.
  *
- * Hover handlers use `Pressable`'s own `onHoverIn` / `onHoverOut` names (web
- * only — no-ops on native). `onFocus` consults `isFocusVisible()` before
- * raising the keyboard-only `focusVisible` layer; `focused` always raises.
+ * 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.
  */
-interface UseGestureHandlers {
-    onPressIn: () => void;
-    onPressOut: () => void;
-    onHoverIn: () => void;
-    onHoverOut: () => void;
-    onFocus: () => void;
-    onBlur: () => void;
-}
-interface UseGestureResult {
-    /** 0↔1 progress for the pressed layer. */
-    pressed: SharedValue<number>;
-    /** 0↔1 progress for the focused layer (any focus modality). */
-    focused: SharedValue<number>;
-    /** 0↔1 progress for the focusVisible layer (keyboard focus only). */
-    focusVisible: SharedValue<number>;
-    /** 0↔1 progress for the hovered layer (web only — stays at 0 on native). */
-    hovered: SharedValue<number>;
-    /** Handlers to spread on the receiving `Pressable`. */
-    handlers: UseGestureHandlers;
+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;
 }
 /**
- * Build a gesture-layer controller. The hook-form of the `gesture` prop —
- * reach for it when you need to drive multiple animated views from the same
- * gesture state (a focus ring + state-layer halo + content tint all on one
- * Pressable), which the prop-form's "animate the receiver's own style" model
- * can't express.
- *
- * Returns four 0↔1 shared values (one per layer) and a handler bag to spread
- * on a `Pressable`. The shared values are stable across renders — feed them
- * into any number of `useAnimatedStyle` blocks anywhere in the tree.
- *
- * Transitions follow the same shape as the `gesture` prop's accompanying
- * `transition`: pass a single `TransitionConfig` to use for every layer, or a
- * `GestureLayerTransitions` map to give each layer its own. Layers without an
- * explicit transition fall back to the library default spring.
+ * 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.
  *
- * Reduced motion (via `<MotionConfig reducedMotion>`) collapses every
- * transition to `no-animation` so state changes snap instead of interpolating
- * — same behaviour the gesture prop applies.
- *
- * @example
  * ```tsx
- * import { useAnimatedStyle } from 'react-native-reanimated'
- * import { useGesture } from '@onlynative/inertia'
- *
- * function Card() {
- *   const { pressed, focused, hovered, handlers } = useGesture({
- *     pressed: { type: 'timing', duration: 100 },
- *     hovered: { type: 'timing', duration: 150 },
- *     focused: { type: 'timing', duration: 200 },
- *   })
- *
- *   const ringStyle = useAnimatedStyle(() => ({ opacity: focused.value }))
- *   const haloStyle = useAnimatedStyle(() => ({
- *     opacity: Math.max(
- *       hovered.value * 0.08,
- *       focused.value * 0.10,
- *       pressed.value * 0.10,
- *     ),
- *   }))
- *
- *   return (
- *     <Pressable {...handlers}>
- *       <Animated.View style={ringStyle} />
- *       <Animated.View style={haloStyle} />
- *     </Pressable>
- *   )
- * }
+ * 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 useGesture(transition?: TransitionConfig | GestureLayerTransitions): UseGestureResult;
+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.
@@ -450,6 +435,61 @@ interface UseScrollResult {
  */
 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
@@ -463,4 +503,4 @@ declare function useScroll(): UseScrollResult;
  */
 declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
 
-export { AnimatableValue, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigValue, Presence, type PresenceContextValue, type ReducedMotion, SpringTransition, TransitionConfig, type UseGestureHandlers, type UseGestureResult, type UseScrollResult, type UseTransformOptions, VariantController, buildReleaseAnimation, createMotionComponent, ensureWorkletEasing, resolveAnimatableValue, resolveTransition, useAnimation, useGesture, useMotionConfig, useMotionValue, usePresence, useScroll, useShouldReduceMotion, useSpring, useTransform, useVariants };
+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 };