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

package/src/types.ts

@@ -298,11 +298,31 @@ export interface MotionProps<C> {
    * — decay is downgraded to spring (no clear target). Reduced motion gates
    * the prop the same way it gates `animate`.
    *
-   * `layoutId` for shared element transitions across screens is deferred:
-   * Reanimated 4 dropped the underlying `sharedTransitionTag` API and a
-   * Inertia-side measure-based registry is the in-flight design.
+   * `layoutId` (below) is a related but distinct mechanism for shared
+   * element transitions across screens — `layout` animates this element's
+   * own layout changes, `layoutId` animates from a different element's
+   * last measured rect to this element's current rect.
    */
   layout?: boolean | TransitionConfig
+  /**
+   * Shared-element transition id. When a Motion primitive with `layoutId`
+   * unmounts, its last on-screen rect is recorded under that id; the next
+   * mount of any Motion primitive with the same id animates from the
+   * recorded rect to its natural position via a FLIP transform stack.
+   *
+   * Reanimated 4 removed the `sharedTransitionTag` API — `layoutId` is the
+   * Inertia-side measure-based replacement. Rects are stored in window
+   * coordinates so the source and target can live on different screens.
+   *
+   * The same `transition` prop drives the FLIP animation (spring by
+   * default; `'timing'` honored; `'decay'` downgrades to spring; reduced
+   * motion skips the transition). Out of scope for the first iteration:
+   * style-prop interpolation (border radius, colors, etc.) — only the
+   * rect-to-rect transform is animated. Two simultaneously-mounted
+   * primitives sharing the same `layoutId` are undefined behavior; pick a
+   * primitive per id at a time.
+   */
+  layoutId?: string
   /**
    * Fired once per logical animation completion. See `AnimationCallbackInfo`
    * for the payload shape — transform parents fire once, not per axis.

package/src/values/index.ts

@@ -1,4 +1,10 @@
 export { useAnimation } from './useAnimation'
+export { useBooleanSpring } from './useBooleanSpring'
+export {
+  useColorTransition,
+  type ColorStyleKey,
+  type UseColorTransitionOptions,
+} from './useColorTransition'
 export {
   useGesture,
   type UseGestureHandlers,
@@ -12,4 +18,9 @@ export {
   type UseTransformOptions,
 } from './useTransform'
 export { useScroll, type UseScrollResult } from './useScroll'
+export {
+  useShadow,
+  type ShadowConfig,
+  type UseShadowOptions,
+} from './useShadow'
 export { useVariants } from './useVariants'

package/src/values/useBooleanSpring.ts

@@ -0,0 +1,33 @@
+import { type SharedValue } from 'react-native-reanimated'
+import { useSpring } from './useSpring'
+import { type SpringTransition } from '../types'
+
+/**
+ * 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.
+ */
+export function useBooleanSpring(
+  active: boolean,
+  springConfig?: SpringTransition,
+): SharedValue<number> {
+  return useSpring(active ? 1 : 0, springConfig)
+}

package/src/values/useColorTransition.ts

@@ -0,0 +1,72 @@
+import {
+  interpolateColor,
+  useAnimatedStyle,
+  type SharedValue,
+} from 'react-native-reanimated'
+
+/**
+ * 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.
+ */
+export type ColorStyleKey =
+  | 'backgroundColor'
+  | 'color'
+  | 'borderColor'
+  | 'borderTopColor'
+  | 'borderRightColor'
+  | 'borderBottomColor'
+  | 'borderLeftColor'
+  | 'tintColor'
+  | 'shadowColor'
+
+export 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.
+ */
+export function useColorTransition(
+  progress: SharedValue<number>,
+  range: readonly [string, string],
+  options?: UseColorTransitionOptions,
+): ReturnType<typeof useAnimatedStyle> {
+  // Resolve the slot key once on the JS thread so the worklet body
+  // consumes a single string literal — consistent with the JS-thread
+  // resolver principle that keeps `Object.keys`-style walks off the UI
+  // thread (see CLAUDE.md design principle 8).
+  const key = options?.key ?? 'backgroundColor'
+  const from = range[0]
+  const to = range[1]
+
+  return useAnimatedStyle(() => {
+    'worklet'
+    return { [key]: interpolateColor(progress.value, [0, 1], [from, to]) }
+  })
+}

package/src/values/useShadow.ts

@@ -0,0 +1,116 @@
+import {
+  interpolate,
+  interpolateColor,
+  useAnimatedStyle,
+  type SharedValue,
+} from 'react-native-reanimated'
+
+/**
+ * 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.
+ */
+export interface ShadowConfig {
+  shadowOpacity?: number
+  shadowRadius?: number
+  shadowOffset?: { width?: number; height?: number }
+  /** Android elevation. iOS shadow consumers can leave this off. */
+  elevation?: number
+  shadowColor?: string
+}
+
+export 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.
+ */
+export function useShadow({
+  from,
+  to,
+  progress,
+}: UseShadowOptions): ReturnType<typeof useAnimatedStyle> {
+  // Resolve presence + endpoints once on the JS thread so the worklet body
+  // consumes flat literals — consistent with the JS-thread resolver
+  // principle that keeps `Object.keys`-style walks off the UI thread.
+  const hasOpacity =
+    from.shadowOpacity !== undefined || to.shadowOpacity !== undefined
+  const hasRadius =
+    from.shadowRadius !== undefined || to.shadowRadius !== undefined
+  const hasElevation =
+    from.elevation !== undefined || to.elevation !== undefined
+  const hasColor =
+    from.shadowColor !== undefined || to.shadowColor !== undefined
+  const hasOffset =
+    from.shadowOffset !== undefined || to.shadowOffset !== undefined
+
+  const opacityFrom = from.shadowOpacity ?? 0
+  const opacityTo = to.shadowOpacity ?? 0
+  const radiusFrom = from.shadowRadius ?? 0
+  const radiusTo = to.shadowRadius ?? 0
+  const elevationFrom = from.elevation ?? 0
+  const elevationTo = to.elevation ?? 0
+  const colorFrom = from.shadowColor ?? 'transparent'
+  const colorTo = to.shadowColor ?? 'transparent'
+  const offsetWFrom = from.shadowOffset?.width ?? 0
+  const offsetWTo = to.shadowOffset?.width ?? 0
+  const offsetHFrom = from.shadowOffset?.height ?? 0
+  const offsetHTo = to.shadowOffset?.height ?? 0
+
+  return useAnimatedStyle(() => {
+    'worklet'
+    const t = progress.value
+    const out: Record<string, unknown> = {}
+    if (hasOpacity) {
+      out.shadowOpacity = interpolate(t, [0, 1], [opacityFrom, opacityTo])
+    }
+    if (hasRadius) {
+      out.shadowRadius = interpolate(t, [0, 1], [radiusFrom, radiusTo])
+    }
+    if (hasElevation) {
+      out.elevation = interpolate(t, [0, 1], [elevationFrom, elevationTo])
+    }
+    if (hasColor) {
+      out.shadowColor = interpolateColor(t, [0, 1], [colorFrom, colorTo])
+    }
+    if (hasOffset) {
+      out.shadowOffset = {
+        width: interpolate(t, [0, 1], [offsetWFrom, offsetWTo]),
+        height: interpolate(t, [0, 1], [offsetHFrom, offsetHTo]),
+      }
+    }
+    return out
+  })
+}