@rootnative/inertia 0.0.0-alpha.0 → 0.0.0-alpha.1

package/src/gestureLayer/useGestureLayer.ts

@@ -5,10 +5,22 @@ import {
   useSharedValue,
   type AnimatedStyle,
 } from 'react-native-reanimated'
-import { useShouldReduceMotion } from '../config'
-import { isTopLevelTransition, resolveTransition } from '../transitions'
+import {
+  resolveNamedTransitionProp,
+  useNamedTransitions,
+  useShouldReduceMotion,
+} from '../config'
+import {
+  isTopLevelTransition,
+  resolveTransition,
+  stableSig,
+} from '../transitions'
 import { useGesture, type UseGestureHandlers } from '../values/useGesture'
-import { type GestureLayerTransitions, type TransitionConfig } from '../types'
+import {
+  type GestureLayerTransitions,
+  type TransitionConfig,
+  type TransitionInput,
+} from '../types'
 
 /**
  * A single gesture-layer style — a flat map of style keys to a value. Numeric
@@ -57,10 +69,11 @@ export interface UseGestureLayerOptions {
   /**
    * Transition forwarded to the underlying `useGesture` hook. Either a single
    * `TransitionConfig` for every gesture layer, or a `GestureLayerTransitions`
-   * map for per-layer fades. Reduced motion collapses every transition to
-   * `no-animation`.
+   * map for per-layer fades. A `TransitionName` registered on the nearest
+   * `<MotionConfig transitions>` is accepted in both positions. Reduced
+   * motion collapses every transition to `no-animation`.
    */
-  transition?: TransitionConfig | GestureLayerTransitions
+  transition?: TransitionInput | GestureLayerTransitions
 }
 
 export interface UseGestureLayerResult {
@@ -128,18 +141,29 @@ export function useGestureLayer(
   states: GestureLayerStates,
   options: UseGestureLayerOptions = {},
 ): UseGestureLayerResult {
-  const { disabled: isDisabled = false, transition } = options
+  const { disabled: isDisabled = false, transition: transitionInput } = options
   const shouldReduceMotion = useShouldReduceMotion()
+  // Resolve registered names here (not just in useGesture) because the
+  // `disabled` layer reads the top-level transition locally. Identity is
+  // preserved when no names are present; when a name resolves, the effect
+  // below keys on the structural signature so a per-render resolve of the
+  // map form doesn't re-fire it.
+  const transition = resolveNamedTransitionProp(
+    transitionInput,
+    useNamedTransitions(),
+  )
   const gesture = useGesture(transition)
   const disabledProgress = useSharedValue(0)
 
+  const transitionSig = stableSig(transition)
   useEffect(() => {
     const target = isDisabled ? 1 : 0
     const cfg = shouldReduceMotion
       ? ({ type: 'no-animation' } as const)
       : (disabledTransition(transition) ?? ({ type: 'spring' } as const))
     disabledProgress.value = resolveTransition(cfg, target) as never
-  }, [isDisabled, shouldReduceMotion, transition, disabledProgress])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isDisabled, shouldReduceMotion, transitionSig, disabledProgress])
 
   // JS-thread precompute: union of keys across all layers, per-key type
   // (number vs color), and a rest-fallback table. The worklet body reads

package/src/index.ts

@@ -18,12 +18,23 @@ export {
   MotionScrollView,
   createMotionComponent,
 } from './motion'
-export { MotionConfig, useMotionConfig, useShouldReduceMotion } from './config'
-export type { MotionConfigValue, ReducedMotion } from './config'
+export {
+  MotionConfig,
+  resolveNamedTransition,
+  useMotionConfig,
+  useNamedTransitions,
+  useShouldReduceMotion,
+} from './config'
+export type {
+  MotionConfigProps,
+  MotionConfigValue,
+  ReducedMotion,
+} from './config'
 export { Presence, usePresence } from './presence'
 export type { PresenceContextValue } from './presence'
 export {
   buildReleaseAnimation,
+  cubicBezier,
   resolveTransition,
   resolveAnimatableValue,
   ensureWorkletEasing,
@@ -56,17 +67,24 @@ export type {
   AnimateStyle,
   AnimationCallbackInfo,
   DecayTransition,
+  EasingFunction,
+  EasingFunctionFactory,
+  EasingInput,
   GestureSubStates,
   MotionComponent,
   MotionProps,
+  NamedTransitions,
   NoAnimationTransition,
   PerPropertyTransition,
+  RegisteredTransitions,
   RepeatConfig,
   SequenceStep,
   SpringTransition,
   TimingTransition,
   Transition,
   TransitionConfig,
+  TransitionInput,
+  TransitionName,
   VariantController,
   VariantsMap,
 } from './types'

package/src/motion/createMotionComponent.tsx

@@ -14,7 +14,12 @@ import Animated, {
   type SharedValue,
 } from 'react-native-reanimated'
 import { type LayoutChangeEvent } from 'react-native'
-import { useShouldReduceMotion } from '../config'
+import {
+  lookupNamedTransition,
+  resolveNamedTransitionProp,
+  useNamedTransitions,
+  useShouldReduceMotion,
+} from '../config'
 import { isFocusVisible } from '../gestures'
 import {
   resolveLayoutTransition,
@@ -167,11 +172,16 @@ const DEFAULT_RESTING: Record<AnimatableKey, number | string> = {
   shadowOffsetHeight: 0,
 }
 
+// Both lookups run after the factory has resolved registered transition
+// names into concrete configs (`resolveNamedTransitionProp`), so the
+// `TransitionInput` values on the map forms are narrowed to `TransitionConfig`
+// here — a string can no longer reach these call sites at runtime.
 function transitionFor<S>(
   prop: keyof S,
   transition: Transition<S> | undefined,
 ): TransitionConfig | undefined {
   if (!transition) return undefined
+  if (typeof transition === 'string') return undefined
   if (isTopLevelTransition(transition)) return transition
   // Gesture-layer keys (`pressed`, `hovered`, …) live on the same map as
   // per-property keys; skip them when looking up a property transition so a
@@ -179,7 +189,9 @@ function transitionFor<S>(
   // style key named `pressed` (none currently exist, but keep the lookup
   // honest).
   if (GESTURE_LAYER_NAME_SET.has(prop as string)) return undefined
-  return (transition as PerPropertyTransition<S>)[prop]
+  return (transition as PerPropertyTransition<S>)[prop] as
+    | TransitionConfig
+    | undefined
 }
 
 function gestureLayerTransitionFor<S>(
@@ -187,8 +199,11 @@ function gestureLayerTransitionFor<S>(
   transition: Transition<S> | undefined,
 ): TransitionConfig | undefined {
   if (!transition) return undefined
+  if (typeof transition === 'string') return undefined
   if (isTopLevelTransition(transition)) return transition
-  return (transition as GestureLayerTransitions)[layer]
+  return (transition as GestureLayerTransitions)[layer] as
+    | TransitionConfig
+    | undefined
 }
 
 /**
@@ -223,11 +238,11 @@ export function createMotionComponent<C extends ComponentType<any>>(
       initial,
       animate,
       exit,
-      transition,
+      transition: transitionProp,
       variants,
       controller,
       gesture,
-      layout,
+      layout: layoutProp,
       layoutId,
       onAnimationEnd,
       style,
@@ -235,11 +250,26 @@ export function createMotionComponent<C extends ComponentType<any>>(
       ...rest
     } = props as Props & {
       style?: unknown
-      layout?: LayoutProp
+      layout?: LayoutProp | string
       layoutId?: string
       onLayout?: (event: LayoutChangeEvent) => void
     }
 
+    // Resolve registered transition names (from the nearest <MotionConfig
+    // transitions>) into concrete configs before anything downstream touches
+    // the props. Resolution is JS-thread and identity-preserving when no
+    // names are present; when names resolve, the registry entries are stable
+    // objects, so every signature-keyed memo below stays warm.
+    const namedTransitions = useNamedTransitions()
+    const transition = resolveNamedTransitionProp(
+      transitionProp as Transition<Record<string, unknown>> | undefined,
+      namedTransitions,
+    )
+    const layout: LayoutProp =
+      typeof layoutProp === 'string'
+        ? lookupNamedTransition(layoutProp, namedTransitions)
+        : layoutProp
+
     // Function-form `style={(state) => ...}` is the Pressable render-prop API.
     // Inertia drives press/focus state through `gesture.*` and merges its own
     // animated style; a function passed here lands inside a style array where

package/src/transitions/cubicBezier.ts

@@ -0,0 +1,126 @@
+import { Easing } from 'react-native-reanimated'
+import { type EasingInput } from '../types'
+
+/**
+ * The CSS easing keywords and their canonical cubic-bezier control points
+ * (W3C css-easing-1). `linear` is special-cased to Reanimated's identity
+ * easing rather than a degenerate bezier.
+ */
+const CSS_KEYWORDS: Record<string, readonly [number, number, number, number]> =
+  {
+    ease: [0.25, 0.1, 0.25, 1],
+    'ease-in': [0.42, 0, 1, 1],
+    'ease-out': [0, 0, 0.58, 1],
+    'ease-in-out': [0.42, 0, 0.58, 1],
+  }
+
+const CSS_FUNCTION = /^cubic-bezier\((.*)\)$/
+
+/**
+ * Build a `timing.easing` value from cubic-bezier control points — as four
+ * numbers, as a W3C CSS `cubic-bezier(...)` string, or as a CSS easing
+ * keyword. Design systems store easing tokens in the CSS format; this helper
+ * makes any such token file directly consumable without hand-translating to
+ * `Easing.bezier` calls:
+ *
+ * ```ts
+ * cubicBezier(0.2, 0, 0, 1)                  // number form
+ * cubicBezier('cubic-bezier(0.2, 0, 0, 1)')  // CSS token form
+ * cubicBezier('ease-out')                    // CSS keywords, incl. 'linear'
+ * ```
+ *
+ * The return value is exactly what `timing.easing` accepts (Reanimated's
+ * bezier factory; the resolver worklet-wraps it via `ensureWorkletEasing`
+ * like every other easing input), so it works in the `transition` prop, in
+ * named transitions registered on `<MotionConfig transitions>`, and in the
+ * value-layer hooks:
+ *
+ * ```tsx
+ * <MotionConfig
+ *   transitions={{
+ *     'state-hover': {
+ *       type: 'timing',
+ *       duration: 150,
+ *       easing: cubicBezier(theme.motion.easingStandard),
+ *     },
+ *   }}
+ * >
+ * ```
+ *
+ * Invalid input **throws** rather than warning: easing tokens are constructed
+ * at theme/module setup, and a malformed token should fail loudly there, not
+ * silently animate with the wrong curve. Per the CSS spec, `x1` / `x2` must
+ * be within `[0, 1]` (`y1` / `y2` are unrestricted). The stepping keywords
+ * (`step-start` / `step-end`) and the CSS `linear(...)` function are not
+ * easing curves this helper produces — they're intentionally unsupported.
+ */
+export function cubicBezier(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+): EasingInput
+export function cubicBezier(css: string): EasingInput
+export function cubicBezier(
+  first: number | string,
+  y1?: number,
+  x2?: number,
+  y2?: number,
+): EasingInput {
+  if (typeof first === 'string') return fromCss(first)
+  return bezier(first, y1 as number, x2 as number, y2 as number, undefined)
+}
+
+function fromCss(input: string): EasingInput {
+  const token = input.trim().toLowerCase()
+  if (token === 'linear') return Easing.linear
+  const keyword = CSS_KEYWORDS[token]
+  if (keyword) return bezier(...keyword, input)
+  const match = CSS_FUNCTION.exec(token)
+  if (!match) {
+    throw new Error(
+      `[inertia] cubicBezier: unsupported easing token ${JSON.stringify(input)}. ` +
+        `Expected four numbers, a 'cubic-bezier(x1, y1, x2, y2)' string, or ` +
+        `one of the CSS keywords 'linear' | 'ease' | 'ease-in' | 'ease-out' ` +
+        `| 'ease-in-out'.`,
+    )
+  }
+  const parts = match[1]!.split(',').map((p) => Number(p.trim()))
+  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+    throw new Error(
+      `[inertia] cubicBezier: could not parse ${JSON.stringify(input)} — ` +
+        `expected exactly four finite numbers inside cubic-bezier(...).`,
+    )
+  }
+  return bezier(parts[0]!, parts[1]!, parts[2]!, parts[3]!, input)
+}
+
+function bezier(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  source: string | undefined,
+): EasingInput {
+  const describe = () =>
+    source !== undefined
+      ? JSON.stringify(source)
+      : `cubicBezier(${x1}, ${y1}, ${x2}, ${y2})`
+  for (const n of [x1, y1, x2, y2]) {
+    if (typeof n !== 'number' || !Number.isFinite(n)) {
+      throw new Error(
+        `[inertia] cubicBezier: ${describe()} — every control point must be ` +
+          `a finite number.`,
+      )
+    }
+  }
+  // CSS (and the underlying bezier solver) require the curve to be a function
+  // of time: x1 / x2 within [0, 1]. y values are unrestricted (overshoot).
+  if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1) {
+    throw new Error(
+      `[inertia] cubicBezier: ${describe()} — x1 and x2 must be within ` +
+        `[0, 1] (got x1=${x1}, x2=${x2}).`,
+    )
+  }
+  return Easing.bezier(x1, y1, x2, y2)
+}

package/src/transitions/index.ts

@@ -1,5 +1,6 @@
 export { resolveTransition } from './resolve'
 export { resolveAnimatableValue } from './resolveSequence'
+export { cubicBezier } from './cubicBezier'
 export { ensureWorkletEasing } from './easing'
 export { isTopLevelTransition, TRANSITION_CONFIG_KEYS } from './keys'
 export { buildReleaseAnimation } from './runtime'

package/src/types.ts

@@ -77,6 +77,57 @@ export type TransitionConfig =
   | DecayTransition
   | NoAnimationTransition
 
+/**
+ * Augmentation point for typed named transitions. Empty by default — the
+ * registry is data fed to `<MotionConfig transitions={...}>` at runtime, so
+ * out of the box any string is accepted wherever a `TransitionName` is.
+ *
+ * Consumers who want their registered names to autocomplete (and typos to be
+ * compile errors) augment this interface with their design system's names:
+ *
+ * ```ts
+ * declare module '@rootnative/inertia' {
+ *   interface RegisteredTransitions {
+ *     'state-hover': TransitionConfig
+ *     'selection': TransitionConfig
+ *   }
+ * }
+ * ```
+ *
+ * The value type is ignored — only the keys matter. Inertia itself never
+ * declares a name here: presets are consumer data, not library surface.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RegisteredTransitions {}
+
+/**
+ * A named transition registered on the nearest `<MotionConfig transitions>`.
+ * Accepted anywhere a `TransitionConfig` is: the `transition` prop (top-level
+ * and per-property), the `layout` prop, and the value-layer hooks. Resolution
+ * happens on the JS thread against the nearest provider; unknown names warn
+ * in dev and fall back to the library default spring.
+ *
+ * Plain `string` until `RegisteredTransitions` is augmented; with an
+ * augmentation in place it narrows to the registered keys.
+ */
+export type TransitionName = keyof RegisteredTransitions extends never
+  ? string
+  : keyof RegisteredTransitions & string
+
+/**
+ * The registry shape accepted by `<MotionConfig transitions={...}>`: named
+ * `TransitionConfig`s. Names are consumer vocabulary (design tokens, semantic
+ * roles); Inertia ships no presets.
+ */
+export type NamedTransitions = Partial<Record<TransitionName, TransitionConfig>>
+
+/**
+ * A transition given either inline (`TransitionConfig`) or by registered name
+ * (`TransitionName`). This is the input type everywhere the public surface
+ * accepts a single transition.
+ */
+export type TransitionInput = TransitionConfig | TransitionName
+
 /**
  * Repeat config — one shape, not three flags. Default `alternate: true`.
  */
@@ -91,7 +142,7 @@ export type RepeatConfig =
  * here.
  */
 export type PerPropertyTransition<S> = {
-  [K in keyof S]?: TransitionConfig
+  [K in keyof S]?: TransitionInput
 }
 
 /**
@@ -104,14 +155,14 @@ export type PerPropertyTransition<S> = {
  * collide with the primitive's inferred style keys.
  */
 export interface GestureLayerTransitions {
-  pressed?: TransitionConfig
-  focused?: TransitionConfig
-  focusVisible?: TransitionConfig
-  hovered?: TransitionConfig
+  pressed?: TransitionInput
+  focused?: TransitionInput
+  focusVisible?: TransitionInput
+  hovered?: TransitionInput
 }
 
 export type Transition<S> =
-  | TransitionConfig
+  | TransitionInput
   | (PerPropertyTransition<S> & GestureLayerTransitions)
 
 /**
@@ -293,7 +344,9 @@ export interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
   gesture?: GestureSubStates<C>
   /**
    * Per-property or top-level transition config. Per-property entries take
-   * precedence over the top-level transition.
+   * precedence over the top-level transition. Anywhere a config object is
+   * accepted (top-level, per-property, per gesture layer) a `TransitionName`
+   * registered on the nearest `<MotionConfig transitions>` is accepted too.
    */
   transition?: Transition<AnimateStyle<C>>
   /**
@@ -305,6 +358,8 @@ export interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
    * - `true` — animate with the library's default spring.
    * - `TransitionConfig` — spring (react-spring vocab) or timing config; the
    *   resolver bridges to Reanimated's `LinearTransition` builder.
+   * - `TransitionName` — a name registered on the nearest
+   *   `<MotionConfig transitions>`.
    * - omitted / `false` — no layout animation (default).
    *
    * Only `'spring'` / `'timing'` / `'no-animation'` map to layout transitions
@@ -316,7 +371,7 @@ export interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
    * own layout changes, `layoutId` animates from a different element's
    * last measured rect to this element's current rect.
    */
-  layout?: boolean | TransitionConfig
+  layout?: boolean | TransitionInput
   /**
    * Shared-element transition id. When a Motion primitive with `layoutId`
    * unmounts, its last on-screen rect is recorded under that id; the next

package/src/values/useAnimation.ts

@@ -1,12 +1,17 @@
 import { useEffect } from 'react'
 import { useSharedValue, type SharedValue } from 'react-native-reanimated'
-import { useShouldReduceMotion } from '../config'
+import {
+  resolveNamedTransition,
+  useNamedTransitions,
+  useShouldReduceMotion,
+} from '../config'
 import { resolveTransition, stableSig } from '../transitions'
-import { type TransitionConfig } from '../types'
+import { type TransitionInput } from '../types'
 
 /**
  * Drive a `SharedValue<number>` toward `target` with **any** transition shape
- * — spring, timing, decay, or no-animation. The general-purpose value-layer
+ * — spring, timing, decay, or no-animation — or a `TransitionName` registered
+ * on the nearest `<MotionConfig transitions>`. The general-purpose value-layer
  * hook: reach for it when you need raw `useSharedValue + useEffect + withX`
  * outside the declarative `animate` flow.
  *
@@ -50,16 +55,17 @@ import { type TransitionConfig } from '../types'
  */
 export function useAnimation(
   target: number,
-  transition?: TransitionConfig,
+  transition?: TransitionInput,
 ): SharedValue<number> {
   const output = useSharedValue<number>(target)
   const shouldReduceMotion = useShouldReduceMotion()
-  const cfgSig = stableSig(transition)
+  const resolved = resolveNamedTransition(transition, useNamedTransitions())
+  const cfgSig = stableSig(resolved)
 
   useEffect(() => {
     const cfg = shouldReduceMotion
       ? ({ type: 'no-animation' } as const)
-      : (transition ?? ({ type: 'spring' } as const))
+      : (resolved ?? ({ type: 'spring' } as const))
     output.value = resolveTransition(cfg, target) as never
     // `output` is identity-stable per hook instance.
     // eslint-disable-next-line react-hooks/exhaustive-deps

package/src/values/useBooleanSpring.ts

@@ -1,6 +1,6 @@
 import { type SharedValue } from 'react-native-reanimated'
 import { useSpring } from './useSpring'
-import { type SpringTransition } from '../types'
+import { type SpringTransition, type TransitionName } from '../types'
 
 /**
  * Toggle a 0↔1 progress value with a spring whenever `active` flips.
@@ -23,11 +23,13 @@ import { type SpringTransition } from '../types'
  *
  * 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.
+ * library's defaults, or pass a `TransitionName` registered on the nearest
+ * `<MotionConfig transitions>` (spring-typed names only — see `useSpring`
+ * for the non-spring fallback behaviour).
  */
 export function useBooleanSpring(
   active: boolean,
-  springConfig?: SpringTransition,
+  springConfig?: SpringTransition | TransitionName,
 ): SharedValue<number> {
   return useSpring(active ? 1 : 0, springConfig)
 }

package/src/values/useGesture.ts

@@ -1,9 +1,17 @@
 import { useCallback, useMemo } from 'react'
 import { useSharedValue, type SharedValue } from 'react-native-reanimated'
-import { useShouldReduceMotion } from '../config'
+import {
+  resolveNamedTransitionProp,
+  useNamedTransitions,
+  useShouldReduceMotion,
+} from '../config'
 import { isFocusVisible } from '../gestures'
 import { isTopLevelTransition, resolveTransition } from '../transitions'
-import { type GestureLayerTransitions, type TransitionConfig } from '../types'
+import {
+  type GestureLayerTransitions,
+  type TransitionConfig,
+  type TransitionInput,
+} from '../types'
 
 type LayerName = 'pressed' | 'focused' | 'focusVisible' | 'hovered'
 
@@ -50,8 +58,10 @@ export interface UseGestureResult {
  *
  * 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.
+ * `GestureLayerTransitions` map to give each layer its own. A `TransitionName`
+ * registered on the nearest `<MotionConfig transitions>` is accepted in both
+ * positions (top-level and per-layer). Layers without an explicit transition
+ * fall back to the library default spring.
  *
  * Reduced motion (via `<MotionConfig reducedMotion>`) collapses every
  * transition to `no-animation` so state changes snap instead of interpolating
@@ -88,19 +98,23 @@ export interface UseGestureResult {
  * ```
  */
 export function useGesture(
-  transition?: TransitionConfig | GestureLayerTransitions,
+  transition?: TransitionInput | GestureLayerTransitions,
 ): UseGestureResult {
   const pressed = useSharedValue(0)
   const focused = useSharedValue(0)
   const focusVisible = useSharedValue(0)
   const hovered = useSharedValue(0)
   const shouldReduceMotion = useShouldReduceMotion()
+  // Registered transition names (top-level string or per-layer string values)
+  // resolve against the nearest <MotionConfig transitions> at render time, so
+  // the callbacks below only ever see concrete configs.
+  const resolved = resolveNamedTransitionProp(transition, useNamedTransitions())
 
   const setLayer = useCallback(
     (sv: SharedValue<number>, layer: LayerName, target: 0 | 1) => {
       const cfg = shouldReduceMotion
         ? ({ type: 'no-animation' } as const)
-        : (layerTransition(layer, transition) ?? ({ type: 'spring' } as const))
+        : (layerTransition(layer, resolved) ?? ({ type: 'spring' } as const))
       sv.value = resolveTransition(cfg, target) as never
     },
     // The transition is intentionally read on every call rather than cooked
@@ -134,11 +148,15 @@ export function useGesture(
   return { pressed, focused, focusVisible, hovered, handlers }
 }
 
+// Runs after name resolution, so the `TransitionInput` values on the map form
+// are concrete configs by the time they're read — hence the return cast.
 function layerTransition(
   layer: LayerName,
   transition: TransitionConfig | GestureLayerTransitions | undefined,
 ): TransitionConfig | undefined {
   if (!transition) return undefined
   if (isTopLevelTransition(transition)) return transition
-  return (transition as GestureLayerTransitions)[layer]
+  return (transition as GestureLayerTransitions)[layer] as
+    | TransitionConfig
+    | undefined
 }

package/src/values/useMotionValue.ts

@@ -26,6 +26,17 @@ import { useSharedValue, type SharedValue } from 'react-native-reanimated'
  * onPress={() => { x.value = 100 }}
  * ```
  */
+// Overloads widen primitive literals: with a bare generic constrained to
+// `number | string`, TS skips literal widening, so `useMotionValue(0)` would
+// infer `SharedValue<0>` and reject every subsequent write. The primitive
+// overloads make `useMotionValue(0)` / `useMotionValue('#fff')` come back as
+// `SharedValue<number>` / `SharedValue<string>`; the generic overload stays
+// last for callers who want an explicit narrower type (e.g. a string union).
+export function useMotionValue(initial: number): SharedValue<number>
+export function useMotionValue(initial: string): SharedValue<string>
+export function useMotionValue<T extends number | string>(
+  initial: T,
+): SharedValue<T>
 export function useMotionValue<T extends number | string>(
   initial: T,
 ): SharedValue<T> {

package/src/values/useScroll.ts

@@ -25,10 +25,13 @@ export interface UseScrollResult {
  * ```tsx
  * const { scrollY, onScroll } = useScroll()
  * const headerOpacity = useTransform(scrollY, [0, 100], [1, 0])
+ * const headerStyle = useAnimatedStyle(() => ({
+ *   opacity: headerOpacity.value,
+ * }))
  *
  * return (
  *   <>
- *     <Motion.View animate={{ opacity: headerOpacity }} />
+ *     <Animated.View style={headerStyle} />
  *     <Motion.ScrollView onScroll={onScroll} scrollEventThrottle={16}>
  *       …
  *     </Motion.ScrollView>
@@ -36,6 +39,10 @@ export interface UseScrollResult {
  * )
  * ```
  *
+ * The derived shared values are consumed through Reanimated interop
+ * (`useAnimatedStyle` / `useDerivedValue`) — the declarative `animate` prop
+ * takes target values, not shared values.
+ *
  * 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.