@rootnative/inertia 0.0.6 → 0.0.7

package/dist/motion/FlatList.d.ts

@@ -0,0 +1,53 @@
+import { FlatListProps, FlatList } from 'react-native';
+import { V as VariantsMap, a as MotionProps } from '../types-DyJpG64F.js';
+import 'react';
+
+/**
+ * Animatable, virtualized `FlatList`.
+ *
+ * Built on Reanimated's `Animated.FlatList` rather than RN's `FlatList`. That
+ * wrapper supplies two things this primitive would otherwise have to
+ * re-implement: the `CellRendererComponent` injection that powers per-row
+ * `itemLayoutAnimation`, and a `scrollEventThrottle` default of 1.
+ *
+ * A note on that throttle default, because the reasoning is easy to get wrong
+ * from Reanimated's own source comment: it says RN defaults FlatList's
+ * `scrollEventThrottle` to 50, which **is stale**. On RN 0.81
+ * (`@react-native/virtualized-lists`, `VirtualizedList.js`) the default is
+ * `props.scrollEventThrottle ?? 0.0001` — effectively every frame. So the
+ * patch is belt-and-braces on current RN rather than the load-bearing reason
+ * to use the wrapper. It is still worth inheriting: it costs nothing, and it
+ * pins the behaviour if RN's default changes again. **Do not restate the "50"
+ * figure as fact** — verify against the installed RN before relying on it.
+ *
+ * This is the primitive that lets one list both virtualize and animate. The
+ * `useScroll()` handler works because `Motion.*` components are Reanimated
+ * animated components — the same mechanism `Motion.ScrollView` relies on, and
+ * nothing about it was ever specific to `ScrollView`:
+ *
+ * ```tsx
+ * const { scrollY, onScroll } = useScroll()
+ *
+ * <Motion.FlatList
+ *   data={items}
+ *   renderItem={renderItem}
+ *   onScroll={onScroll}
+ *   initial={{ opacity: 0 }}
+ *   animate={{ opacity: 1 }}
+ * />
+ * ```
+ *
+ * Two scoping notes:
+ *
+ * - `animate` / `initial` / `gesture` apply to the **scroll container**, not to
+ *   rows. Animate rows by using a `Motion.*` primitive inside `renderItem`.
+ * - The `layout` prop animates the list frame. Per-row layout animation is
+ *   Reanimated's `itemLayoutAnimation`, which is forwarded through untouched.
+ *   Note that row-level layout animation can fight the list's own measurement
+ *   passes — measure before adopting it.
+ */
+declare const MotionFlatList: <ItemT = any, V extends VariantsMap<FlatListProps<ItemT>> = VariantsMap<FlatListProps<ItemT>>>(props: FlatListProps<ItemT> & MotionProps<FlatListProps<ItemT>, V> & {
+    ref?: React.Ref<FlatList<ItemT>>;
+}) => React.ReactElement;
+
+export { MotionFlatList };

package/dist/motion/FlatList.js

@@ -0,0 +1,13 @@
+'use strict';
+
+var chunkQJYFTTM2_js = require('../chunk-QJYFTTM2.js');
+require('../chunk-6V7MOBXO.js');
+require('../chunk-OBRGJAST.js');
+require('../chunk-PM6CVGXJ.js');
+
+
+
+Object.defineProperty(exports, "MotionFlatList", {
+  enumerable: true,
+  get: function () { return chunkQJYFTTM2_js.MotionFlatList; }
+});

package/dist/motion/FlatList.mjs

@@ -0,0 +1,4 @@
+export { MotionFlatList } from '../chunk-ZOBOKLAS.mjs';
+import '../chunk-HPJMIBBK.mjs';
+import '../chunk-Z3HCJ43H.mjs';
+import '../chunk-REYL77RE.mjs';

package/dist/motion/Image.d.mts

@@ -1,5 +1,5 @@
 import { Image } from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.mjs';
+import { M as MotionComponent } from '../types-DyJpG64F.mjs';
 import 'react';
 
 /**

package/dist/motion/Image.d.ts

@@ -1,5 +1,5 @@
 import { Image } from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.js';
+import { M as MotionComponent } from '../types-DyJpG64F.js';
 import 'react';
 
 /**

package/dist/motion/Image.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkFWWVHLXB_js = require('../chunk-FWWVHLXB.js');
-require('../chunk-767UKZXG.js');
+var chunkYUTS6JRU_js = require('../chunk-YUTS6JRU.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionImage", {
   enumerable: true,
-  get: function () { return chunkFWWVHLXB_js.MotionImage; }
+  get: function () { return chunkYUTS6JRU_js.MotionImage; }
 });

package/dist/motion/Image.mjs

@@ -1,4 +1,4 @@
-export { MotionImage } from '../chunk-PFPO7DX2.mjs';
-import '../chunk-2ICQLWH2.mjs';
+export { MotionImage } from '../chunk-KBFN4TRO.mjs';
+import '../chunk-HPJMIBBK.mjs';
 import '../chunk-Z3HCJ43H.mjs';
 import '../chunk-REYL77RE.mjs';

package/dist/motion/Pressable.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.mjs';
+import { M as MotionComponent } from '../types-DyJpG64F.mjs';
 
 /**
  * Animatable `Pressable`. The `gesture` prop's `pressed` sub-state hooks into

package/dist/motion/Pressable.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.js';
+import { M as MotionComponent } from '../types-DyJpG64F.js';
 
 /**
  * Animatable `Pressable`. The `gesture` prop's `pressed` sub-state hooks into

package/dist/motion/Pressable.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk5MGWHOSV_js = require('../chunk-5MGWHOSV.js');
-require('../chunk-767UKZXG.js');
+var chunkWGCF3WQG_js = require('../chunk-WGCF3WQG.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionPressable", {
   enumerable: true,
-  get: function () { return chunk5MGWHOSV_js.MotionPressable; }
+  get: function () { return chunkWGCF3WQG_js.MotionPressable; }
 });

package/dist/motion/Pressable.mjs

@@ -1,4 +1,4 @@
-export { MotionPressable } from '../chunk-C3EDC5ZW.mjs';
-import '../chunk-2ICQLWH2.mjs';
+export { MotionPressable } from '../chunk-52QSN2VQ.mjs';
+import '../chunk-HPJMIBBK.mjs';
 import '../chunk-Z3HCJ43H.mjs';
 import '../chunk-REYL77RE.mjs';

package/dist/motion/ScrollView.d.mts

@@ -1,5 +1,5 @@
 import { ScrollView } from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.mjs';
+import { M as MotionComponent } from '../types-DyJpG64F.mjs';
 import 'react';
 
 /**

package/dist/motion/ScrollView.d.ts

@@ -1,5 +1,5 @@
 import { ScrollView } from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.js';
+import { M as MotionComponent } from '../types-DyJpG64F.js';
 import 'react';
 
 /**

package/dist/motion/ScrollView.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkX7B5WR5A_js = require('../chunk-X7B5WR5A.js');
-require('../chunk-767UKZXG.js');
+var chunkQYR66E2G_js = require('../chunk-QYR66E2G.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionScrollView", {
   enumerable: true,
-  get: function () { return chunkX7B5WR5A_js.MotionScrollView; }
+  get: function () { return chunkQYR66E2G_js.MotionScrollView; }
 });

package/dist/motion/ScrollView.mjs

@@ -1,4 +1,4 @@
-export { MotionScrollView } from '../chunk-BAAQI37F.mjs';
-import '../chunk-2ICQLWH2.mjs';
+export { MotionScrollView } from '../chunk-VSK2E35J.mjs';
+import '../chunk-HPJMIBBK.mjs';
 import '../chunk-Z3HCJ43H.mjs';
 import '../chunk-REYL77RE.mjs';

package/dist/motion/Text.d.mts

@@ -1,5 +1,5 @@
 import { Text } from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.mjs';
+import { M as MotionComponent } from '../types-DyJpG64F.mjs';
 import 'react';
 
 /**

package/dist/motion/Text.d.ts

@@ -1,5 +1,5 @@
 import { Text } from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.js';
+import { M as MotionComponent } from '../types-DyJpG64F.js';
 import 'react';
 
 /**

package/dist/motion/Text.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkSTARIT6W_js = require('../chunk-STARIT6W.js');
-require('../chunk-767UKZXG.js');
+var chunkZSOCRHU3_js = require('../chunk-ZSOCRHU3.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionText", {
   enumerable: true,
-  get: function () { return chunkSTARIT6W_js.MotionText; }
+  get: function () { return chunkZSOCRHU3_js.MotionText; }
 });

package/dist/motion/Text.mjs

@@ -1,4 +1,4 @@
-export { MotionText } from '../chunk-F7LJX56B.mjs';
-import '../chunk-2ICQLWH2.mjs';
+export { MotionText } from '../chunk-WMLS4TMX.mjs';
+import '../chunk-HPJMIBBK.mjs';
 import '../chunk-Z3HCJ43H.mjs';
 import '../chunk-REYL77RE.mjs';

package/dist/motion/View.d.mts

@@ -1,5 +1,5 @@
 import { View } from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.mjs';
+import { M as MotionComponent } from '../types-DyJpG64F.mjs';
 import 'react';
 
 /**

package/dist/motion/View.d.ts

@@ -1,5 +1,5 @@
 import { View } from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.js';
+import { M as MotionComponent } from '../types-DyJpG64F.js';
 import 'react';
 
 /**

package/dist/motion/View.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkK5SI6VXS_js = require('../chunk-K5SI6VXS.js');
-require('../chunk-767UKZXG.js');
+var chunkNPJ46457_js = require('../chunk-NPJ46457.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionView", {
   enumerable: true,
-  get: function () { return chunkK5SI6VXS_js.MotionView; }
+  get: function () { return chunkNPJ46457_js.MotionView; }
 });

package/dist/motion/View.mjs

@@ -1,4 +1,4 @@
-export { MotionView } from '../chunk-CMHVF6F4.mjs';
-import '../chunk-2ICQLWH2.mjs';
+export { MotionView } from '../chunk-RUIOM2YZ.mjs';
+import '../chunk-HPJMIBBK.mjs';
 import '../chunk-Z3HCJ43H.mjs';
 import '../chunk-REYL77RE.mjs';

package/dist/touch/index.d.mts

@@ -1,6 +1,6 @@
 import { PanResponderInstance } from 'react-native';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig } from '../types-BQgLJeQG.mjs';
+import { T as TransitionConfig } from '../types-DyJpG64F.mjs';
 import 'react';
 
 /**

package/dist/touch/index.d.ts

@@ -1,6 +1,6 @@
 import { PanResponderInstance } from 'react-native';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig } from '../types-BQgLJeQG.js';
+import { T as TransitionConfig } from '../types-DyJpG64F.js';
 import 'react';
 
 /**

package/dist/{types-BQgLJeQG.d.mts → types-DyJpG64F.d.mts}

@@ -456,4 +456,4 @@ interface MotionComponent<C extends ComponentType<any>> {
     displayName?: string;
 }
 
-export type { AnimatableValue as A, BoxShadowInput as B, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantController as V, TransitionInput as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, GestureSubStates as g, MotionProps as h, NoAnimationTransition as i, RepeatConfig as j, SequenceStep as k, TimingTransition as l, Transition as m, VariantsMap as n };
+export type { AnimatableValue as A, BoxShadowInput as B, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantsMap as V, MotionProps as a, TransitionInput as b, TransitionName as c, VariantController as d, AnimateStyle as e, AnimationCallbackInfo as f, EasingFunction as g, EasingFunctionFactory as h, GestureSubStates as i, NoAnimationTransition as j, RepeatConfig as k, SequenceStep as l, TimingTransition as m, Transition as n };

package/dist/{types-BQgLJeQG.d.ts → types-DyJpG64F.d.ts}

@@ -456,4 +456,4 @@ interface MotionComponent<C extends ComponentType<any>> {
     displayName?: string;
 }
 
-export type { AnimatableValue as A, BoxShadowInput as B, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantController as V, TransitionInput as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, GestureSubStates as g, MotionProps as h, NoAnimationTransition as i, RepeatConfig as j, SequenceStep as k, TimingTransition as l, Transition as m, VariantsMap as n };
+export type { AnimatableValue as A, BoxShadowInput as B, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantsMap as V, MotionProps as a, TransitionInput as b, TransitionName as c, VariantController as d, AnimateStyle as e, AnimationCallbackInfo as f, EasingFunction as g, EasingFunctionFactory as h, GestureSubStates as i, NoAnimationTransition as j, RepeatConfig as k, SequenceStep as l, TimingTransition as m, Transition as n };

package/dist/{useGesture-DfaTx-3t.d.mts → useGesture-CnZQnYHH.d.mts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { a as TransitionInput, G as GestureLayerTransitions } from './types-BQgLJeQG.mjs';
+import { b as TransitionInput, G as GestureLayerTransitions } from './types-DyJpG64F.mjs';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/dist/{useGesture-B0_CzOUz.d.ts → useGesture-DbH46EBp.d.ts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { a as TransitionInput, G as GestureLayerTransitions } from './types-BQgLJeQG.js';
+import { b as TransitionInput, G as GestureLayerTransitions } from './types-DyJpG64F.js';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/jest-setup.js

@@ -45,7 +45,7 @@ jest.mock('react-native/Libraries/Text/Text', () => {
 //      run; targets snap in one step.
 jest.mock('react-native-reanimated', () => {
   const React = require('react')
-  const { Image, ScrollView, Text, View } = require('react-native')
+  const { FlatList, Image, ScrollView, Text, View } = require('react-native')
 
   const wrap = (Component, displayName) => {
     const Wrapped = React.forwardRef((props, ref) =>
@@ -59,6 +59,10 @@ jest.mock('react-native-reanimated', () => {
   const AnimatedText = wrap(Text, 'Animated.Text')
   const AnimatedImage = wrap(Image, 'Animated.Image')
   const AnimatedScrollView = wrap(ScrollView, 'Animated.ScrollView')
+  // Reanimated's real `Animated.FlatList` also defaults `scrollEventThrottle`
+  // to 1 and injects a `CellRendererComponent`; neither is observable in this
+  // mock, so the wrapper is a plain pass-through like the others.
+  const AnimatedFlatList = wrap(FlatList, 'Animated.FlatList')
 
   return {
     __esModule: true,
@@ -67,6 +71,7 @@ jest.mock('react-native-reanimated', () => {
       Text: AnimatedText,
       Image: AnimatedImage,
       ScrollView: AnimatedScrollView,
+      FlatList: AnimatedFlatList,
       createAnimatedComponent: (c) =>
         wrap(c, `Animated(${c.displayName ?? c.name ?? 'Component'})`),
     },
@@ -74,6 +79,7 @@ jest.mock('react-native-reanimated', () => {
     Text: AnimatedText,
     Image: AnimatedImage,
     ScrollView: AnimatedScrollView,
+    FlatList: AnimatedFlatList,
     useSharedValue: (initial) => {
       const ref = React.useRef(null)
       if (ref.current === null) ref.current = { value: initial }

package/llms.txt

@@ -34,17 +34,21 @@ import {
 import { useGestureLayer } from '@rootnative/inertia/gesture-layer'
 // Render-layer Reanimated interop for custom animated components:
 import { Animated, useAnimatedStyle } from '@rootnative/inertia/reanimated'
-// or for tree-shaking the primitives:
+// or for tree-shaking the primitives. NOTE: these subpaths export a
+// differently NAMED symbol — `MotionScrollView`, not `Motion.ScrollView`.
+// `Motion` itself is only exported from the package root above, and there
+// is no '@rootnative/inertia/motion' subpath.
 import { MotionView } from '@rootnative/inertia/view'
 import { MotionText } from '@rootnative/inertia/text'
 import { MotionImage } from '@rootnative/inertia/image'
 import { MotionPressable } from '@rootnative/inertia/pressable'
 import { MotionScrollView } from '@rootnative/inertia/scroll-view'
+import { MotionFlatList } from '@rootnative/inertia/flat-list'
 ```
 
 ## Public API
 
-- `Motion.View` / `Motion.Text` / `Motion.Image` / `Motion.Pressable` / `Motion.ScrollView` — animatable primitives. Per-primitive style inference (no shared `ViewStyle & TextStyle & ImageStyle` fallback).
+- `Motion.View` / `Motion.Text` / `Motion.Image` / `Motion.Pressable` / `Motion.ScrollView` / `Motion.FlatList` — animatable primitives. Per-primitive style inference (no shared `ViewStyle & TextStyle & ImageStyle` fallback). `Motion.FlatList` is the **virtualized** animated scroller: it takes `useScroll`'s `onScroll` handler and keeps `data` / `renderItem` item-type inference, so a long list can virtualize and animate at once. Animation props apply to the scroll container; animate rows with a `Motion.*` inside `renderItem`.
 - `<Presence>` — mount / unmount transitions; children need explicit `key`s. Exiting children get `pointerEvents: 'none'` automatically.
 - `<MotionConfig reducedMotion="user" | "never" | "always" transitions={{ name: TransitionConfig }}>` — gates motion against the OS reduce-motion setting (default `"user"`) and registers named transitions for the subtree. A registered name is accepted anywhere a `TransitionConfig` is: the `transition` prop (top-level and per-property/per-layer), the `layout` prop, and the value-layer hooks (`transition="selection"`, `useBooleanSpring(checked, 'selection')`). Nested providers merge (child overrides per name); unknown names warn in dev and fall back to the default spring. Names are consumer vocabulary — no presets ship with the library. Optional compile-time narrowing via `declare module '@rootnative/inertia' { interface RegisteredTransitions { ... } }`. Custom components join the registry with `useNamedTransitions()` + `resolveNamedTransition(input, registry)`.
 - `useGesture(transition?)` — hook-form of the `gesture` prop. Returns 0↔1 progress shared values (`pressed`, `focused`, `focusVisible`, `hovered`) plus a `handlers` bag to spread on a `Pressable`. Use when one gesture needs to drive multiple animated siblings (focus rings, MD3 state-layer halos, multi-element compositions).
@@ -60,7 +64,7 @@ import { MotionScrollView } from '@rootnative/inertia/scroll-view'
 - `useColorTransition(progress, [from, to], options?)` — pure value-layer interpolator for a single color channel, driven by a `SharedValue<number>` (0→1). Returns an animated style fragment with one color key (default `backgroundColor`; configurable via `options.key` to `color` / `borderColor` / `tintColor` / `shadowColor` / per-side border colors). For raw `SharedValue<string>` output, use `useTransform(progress, [0, 1], [from, to])` instead.
 - `useColorCascade(rest, layers, options?)` — pure value-layer interpolator compositing a **priority-ordered** stack of color layers over a base `rest` color; each `layers` entry is `{ progress: SharedValue<number>, color: string }`, later entries win as their progress rises (equivalent to the nested `focus(error(hover(rest)))` `interpolateColor` chain). `options.key` reuses `ColorStyleKey` (default `backgroundColor`). Returns a spreadable animated style fragment; memoized on a colors+key signature. Color-only by design — cascade a numeric key separately via `useInterpolatedStyle` + `useTransform` max. `useColorTransition` stays the single-layer fast path.
 - `useInterpolatedStyle(progress, map, options?)` — pure value-layer interpolator mapping one `SharedValue<number>` onto **N** style props at once, returned as a spreadable animated style fragment (the multi-key, style-fragment counterpart to `useTransform`'s output-range form). Numeric keys (`opacity` / `height` / `fontSize` / …) route through `interpolate`; transform keys (`translateX` / `scale` / `rotate` / …) lift into a `transform` array in map key-order (`rotate*` emit `'<n>deg'`); color keys (`backgroundColor` / `borderColor` / …) route through `interpolateColor` (a multi-stop `useColorTransition`). Stop types are compile-checked. `options.inputRange` (default `[0,1]` / evenly-spaced) and `options.extrapolate` (default `'clamp'`) apply to every key. Memoized on an order-preserving signature. For function-valued or multi-source composition, drop to `useTransform`'s worklet form or a hand-rolled `useAnimatedStyle`.
-- `useScroll()` — returns `{ scrollX, scrollY, onScroll }` for use with `Motion.ScrollView`. Scroll events fire on the UI thread.
+- `useScroll()` — returns `{ scrollX, scrollY, onScroll }` for use with `Motion.ScrollView` or `Motion.FlatList`. Scroll events fire on the UI thread. Set `scrollEventThrottle={16}` on a `Motion.ScrollView`; `Motion.FlatList` defaults it to 1.
 - `createMotionComponent<C>(C)` — wrap any component with the same Motion prop surface, inferring style from `C`.
 - `buildReleaseAnimation(transition, toValue)` — worklet-safe single-step animation builder (spring / timing / decay / no-animation). For assigning Inertia-resolved animations to shared values from inside a gesture worklet. Used internally by `@rootnative/inertia-gestures`'s `useDrag({ onRelease })`.
 - `resolveTransition(config, toValue, callback?)` — JS-thread resolver: bakes a `TransitionConfig` + target into a Reanimated animation (`withSpring` / `withTiming` / `withDecay`, plus `delay` / `repeat` wrapping) ready to assign to a shared value. The building block for custom animated components that accept Inertia's `transition` shape; this is what the gradient and SVG adapter packages use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "RootNative",
@@ -72,6 +72,13 @@
       "import": "./dist/motion/ScrollView.mjs",
       "require": "./dist/motion/ScrollView.js"
     },
+    "./flat-list": {
+      "types": "./dist/motion/FlatList.d.ts",
+      "react-native": "./src/motion/FlatList.tsx",
+      "source": "./src/motion/FlatList.tsx",
+      "import": "./dist/motion/FlatList.mjs",
+      "require": "./dist/motion/FlatList.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "react-native": "./src/testing/index.ts",

package/src/index.ts

@@ -16,6 +16,7 @@ export {
   MotionImage,
   MotionPressable,
   MotionScrollView,
+  MotionFlatList,
   createMotionComponent,
 } from './motion'
 export {

package/src/motion/FlatList.tsx

@@ -0,0 +1,77 @@
+import type { FlatList as RNFlatList, FlatListProps } from 'react-native'
+import Animated from 'react-native-reanimated'
+import type { MotionProps, VariantsMap } from '../types'
+import { createMotionComponent } from './createMotionComponent'
+
+/**
+ * Animatable, virtualized `FlatList`.
+ *
+ * Built on Reanimated's `Animated.FlatList` rather than RN's `FlatList`. That
+ * wrapper supplies two things this primitive would otherwise have to
+ * re-implement: the `CellRendererComponent` injection that powers per-row
+ * `itemLayoutAnimation`, and a `scrollEventThrottle` default of 1.
+ *
+ * A note on that throttle default, because the reasoning is easy to get wrong
+ * from Reanimated's own source comment: it says RN defaults FlatList's
+ * `scrollEventThrottle` to 50, which **is stale**. On RN 0.81
+ * (`@react-native/virtualized-lists`, `VirtualizedList.js`) the default is
+ * `props.scrollEventThrottle ?? 0.0001` — effectively every frame. So the
+ * patch is belt-and-braces on current RN rather than the load-bearing reason
+ * to use the wrapper. It is still worth inheriting: it costs nothing, and it
+ * pins the behaviour if RN's default changes again. **Do not restate the "50"
+ * figure as fact** — verify against the installed RN before relying on it.
+ *
+ * This is the primitive that lets one list both virtualize and animate. The
+ * `useScroll()` handler works because `Motion.*` components are Reanimated
+ * animated components — the same mechanism `Motion.ScrollView` relies on, and
+ * nothing about it was ever specific to `ScrollView`:
+ *
+ * ```tsx
+ * const { scrollY, onScroll } = useScroll()
+ *
+ * <Motion.FlatList
+ *   data={items}
+ *   renderItem={renderItem}
+ *   onScroll={onScroll}
+ *   initial={{ opacity: 0 }}
+ *   animate={{ opacity: 1 }}
+ * />
+ * ```
+ *
+ * Two scoping notes:
+ *
+ * - `animate` / `initial` / `gesture` apply to the **scroll container**, not to
+ *   rows. Animate rows by using a `Motion.*` primitive inside `renderItem`.
+ * - The `layout` prop animates the list frame. Per-row layout animation is
+ *   Reanimated's `itemLayoutAnimation`, which is forwarded through untouched.
+ *   Note that row-level layout animation can fight the list's own measurement
+ *   passes — measure before adopting it.
+ */
+export const MotionFlatList = createMotionComponent(
+  Animated.FlatList as never,
+  // `createMotionComponent<C>` returns a non-generic `MotionComponent<C>`, so
+  // `data` / `renderItem` would collapse to `any` and lose `ItemT` inference.
+  // Restore it with the same call-signature cast Reanimated itself uses for
+  // this exact problem (see its `ReanimatedFlatList` export, and the
+  // `@ts-expect-error` above `AnimatedFlatList` explaining that
+  // `createAnimatedComponent` cannot create generic components).
+  //
+  // **Both** generics live on the one call signature, and that is deliberate:
+  // `ItemT` infers from `data` while `V` infers from `variants`, independently.
+  // Declaring only `ItemT` (the obvious first cut) silently drops the
+  // variant-key narrowing that `MotionComponent` provides on every other
+  // primitive — `animate="typo"` would stop being a compile error here and
+  // nowhere else. Both directions are pinned in
+  // `__type-tests__/flat-list.test-d.tsx`.
+) as unknown as <
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ItemT = any,
+  V extends VariantsMap<FlatListProps<ItemT>> = VariantsMap<
+    FlatListProps<ItemT>
+  >,
+>(
+  props: FlatListProps<ItemT> &
+    MotionProps<FlatListProps<ItemT>, V> & {
+      ref?: React.Ref<RNFlatList<ItemT>>
+    },
+) => React.ReactElement

package/src/motion/createMotionComponent.tsx

@@ -2025,6 +2025,26 @@ function useGestureHandlers(
       // forward to those when present so wrapping consumers stay consistent.
       handlers.onPressIn = compose(rest.onPressIn, () => setPressed(true))
       handlers.onPressOut = compose(rest.onPressOut, () => setPressed(false))
+      // Web pointer events. `onTouchStart` reaches the DOM as a real
+      // `touchstart` listener under react-native-web, which a mouse never
+      // fires — so without these a plain `Motion.View` (anything that isn't a
+      // Pressable, i.e. has no `onPressIn` path) was inert under a desktop
+      // click while `Motion.Pressable` worked. Pointer events cover mouse, pen
+      // and touch, so `pressed` means "any pointer" on every platform.
+      //
+      // A web touch fires `touchstart` *and* `pointerdown`; both set the same
+      // boolean to the same value, so the overlap is idempotent, not a
+      // double-toggle. React Native has no pointer props, so these are inert
+      // on native and cost nothing there.
+      handlers.onPointerDown = compose(rest.onPointerDown, () =>
+        setPressed(true),
+      )
+      handlers.onPointerUp = compose(rest.onPointerUp, () => setPressed(false))
+      // Fires when the browser takes over the gesture (scroll, drag start) —
+      // without it the pressed layer would stick on after the pointer is gone.
+      handlers.onPointerCancel = compose(rest.onPointerCancel, () =>
+        setPressed(false),
+      )
     }
     // Mount onFocus/onBlur if either focus sub-state is declared. The two flags
     // are independent: `focused` always tracks focus; `focusVisible` only
@@ -2061,6 +2081,9 @@ function useGestureHandlers(
     rest.onTouchCancel,
     rest.onPressIn,
     rest.onPressOut,
+    rest.onPointerDown,
+    rest.onPointerUp,
+    rest.onPointerCancel,
     rest.onFocus,
     rest.onBlur,
     rest.onMouseEnter,

package/src/motion/index.ts

@@ -1,3 +1,4 @@
+import { MotionFlatList } from './FlatList'
 import { MotionImage } from './Image'
 import { MotionPressable } from './Pressable'
 import { MotionScrollView } from './ScrollView'
@@ -11,6 +12,7 @@ export {
   MotionImage,
   MotionPressable,
   MotionScrollView,
+  MotionFlatList,
 }
 
 /**
@@ -23,4 +25,5 @@ export const Motion = {
   Image: MotionImage,
   Pressable: MotionPressable,
   ScrollView: MotionScrollView,
+  FlatList: MotionFlatList,
 } as const

package/src/values/useScroll.ts

@@ -11,10 +11,10 @@ export interface UseScrollResult {
   /** 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.
+   * Handler to pass to the `onScroll` prop of `Motion.ScrollView` or
+   * `Motion.FlatList` (or any other Reanimated animated scroller). 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
 }
@@ -47,9 +47,13 @@ export interface UseScrollResult {
  * read from any worklet (`useAnimatedStyle`, `useDerivedValue`,
  * `useTransform`) without a JS-thread bounce.
  *
- * Remember to set `scrollEventThrottle={16}` on the `ScrollView` for 60Hz
+ * Remember to set `scrollEventThrottle={16}` on a `Motion.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.
+ *
+ * `Motion.FlatList` needs no such setting — it defaults `scrollEventThrottle`
+ * to 1 for you. Prefer it over `Motion.ScrollView` for long or unbounded lists:
+ * it virtualizes, and both accept this handler.
  */
 export function useScroll(): UseScrollResult {
   const scrollX = useSharedValue(0)

package/dist/chunk-FWWVHLXB.js

@@ -1,8 +0,0 @@
-'use strict';
-
-var chunk767UKZXG_js = require('./chunk-767UKZXG.js');
-var reactNative = require('react-native');
-
-var MotionImage = chunk767UKZXG_js.createMotionComponent(reactNative.Image);
-
-exports.MotionImage = MotionImage;

package/dist/chunk-K5SI6VXS.js

@@ -1,8 +0,0 @@
-'use strict';
-
-var chunk767UKZXG_js = require('./chunk-767UKZXG.js');
-var reactNative = require('react-native');
-
-var MotionView = chunk767UKZXG_js.createMotionComponent(reactNative.View);
-
-exports.MotionView = MotionView;