@rootnative/inertia 0.0.5 → 0.0.7

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

@@ -23,11 +23,18 @@ import {
 } from '../config'
 import { isFocusVisible } from '../gestures'
 import {
+  layersToPayload,
   normalizeBoxShadow,
+  payloadToLayers,
   prepareBoxShadowAnimation,
-  type AnimatedBoxShadowLayer,
+  type BoxShadowPayload,
   type SplitBoxShadow,
 } from '../internal/boxShadow'
+import {
+  normalizeAnimatableColor,
+  normalizeAnimatableColorTarget,
+  TRANSPARENT,
+} from '../internal/color'
 import { warnOnce } from '../internal/warnOnce'
 import {
   resolveLayoutTransition,
@@ -191,16 +198,20 @@ const COLOR_KEYS = [
 const SHADOW_OFFSET_KEYS = ['shadowOffsetWidth', 'shadowOffsetHeight'] as const
 
 // Keys whose shared value holds a structure rather than a scalar. `boxShadow`
-// is the only one: its slot carries an array of layer objects, which
+// is the only one: its slot carries the layers keyed by index, which
 // Reanimated's animation drivers recurse into, animating each leaf number and
-// color independently (`arrayOnStart` → `objectOnStart` in Reanimated's
-// `animation/util.ts`).
+// color independently (`objectOnStart` in Reanimated's `animation/util.ts`).
+//
+// Index-keyed and not an array, which is load-bearing — Reanimated recurses
+// into objects but not into arrays. See `BoxShadowPayload` for the mechanism
+// and for what it looked like when this was an array (`0.0.4`/`0.0.5`: dead
+// under the default spring, silently correct-looking under timing).
 //
-// Passing the CSS string through instead would NOT work — a box-shadow string
-// isn't a color, so it lands in Reanimated's prefix-number-suffix branch,
-// which is built for values like '100%' and would pull a single number out of
-// a four-value shadow. All string parsing therefore happens on the JS thread,
-// once per change, in `internal/boxShadow.ts`.
+// Passing the CSS string through instead would NOT work either — a box-shadow
+// string isn't a color, so it lands in Reanimated's prefix-number-suffix
+// branch, which is built for values like '100%' and would pull a single number
+// out of a four-value shadow. All string parsing therefore happens on the JS
+// thread, once per change, in `internal/boxShadow.ts`.
 const STRUCTURED_KEYS = ['boxShadow'] as const
 
 // Keys a shared-element transition (`layoutId`) carries from the source
@@ -253,15 +264,16 @@ const SHARED_STYLE_KEY_SET = new Set<AnimatableKey>(SHARED_STYLE_KEYS)
 
 /**
  * What a per-key shared value can hold. Scalars for every key except
- * `boxShadow`, whose slot carries the layer array (see `STRUCTURED_KEYS`).
+ * `boxShadow`, whose slot carries the index-keyed layer payload (see
+ * `STRUCTURED_KEYS`).
  */
-type AnimatableSlotValue = number | string | readonly AnimatedBoxShadowLayer[]
+type AnimatableSlotValue = number | string | BoxShadowPayload
 
 /**
  * Resting `boxShadow` — no shadow at all. Frozen and hoisted so every
  * primitive shares one reference and an untouched slot never allocates.
  */
-const NO_BOX_SHADOW: readonly AnimatedBoxShadowLayer[] = Object.freeze([])
+const NO_BOX_SHADOW: BoxShadowPayload = Object.freeze({})
 
 const GESTURE_LAYER_NAMES = [
   'hovered',
@@ -341,15 +353,21 @@ const DEFAULT_RESTING: Record<AnimatableKey, AnimatableSlotValue> = {
   gap: 0,
   rowGap: 0,
   columnGap: 0,
-  // 'transparent' is the only safe universal default for colors: it works as
-  // an initial seed for any color animation (no jarring opaque flash on mount
-  // when `initial` is omitted) and rgba(0,0,0,0) interpolates cleanly into
-  // any opaque target via Reanimated's color util.
-  backgroundColor: 'transparent',
-  borderColor: 'transparent',
-  color: 'transparent',
-  tintColor: 'transparent',
-  shadowColor: 'transparent',
+  // Fully transparent black is the only safe universal default for colors: it
+  // works as an initial seed for any color animation (no jarring opaque flash
+  // on mount when `initial` is omitted) and interpolates cleanly into any
+  // opaque target.
+  //
+  // Spelled `rgba(0, 0, 0, 0)` and NOT `'transparent'`, which is not optional.
+  // Reanimated's color-name table maps `transparent` to `undefined`, so it is
+  // the one named color `isColor()` rejects — a slot resting at the keyword
+  // takes the prefix-number-suffix branch on its next animation and produces
+  // `NaN` instead of a color. See `TRANSPARENT` in `internal/boxShadow.ts`.
+  backgroundColor: TRANSPARENT,
+  borderColor: TRANSPARENT,
+  color: TRANSPARENT,
+  tintColor: TRANSPARENT,
+  shadowColor: TRANSPARENT,
   shadowOffsetWidth: 0,
   shadowOffsetHeight: 0,
   boxShadow: NO_BOX_SHADOW,
@@ -730,12 +748,20 @@ export function createMotionComponent<C extends ComponentType<any>>(
               const raw = flat.boxShadow as BoxShadowInput | undefined
               if (raw !== undefined) {
                 styleRestingShadow = normalizeBoxShadow(raw)
-                styleResting.boxShadow = styleRestingShadow.layers
+                styleResting.boxShadow = layersToPayload(
+                  styleRestingShadow.layers,
+                )
               }
               continue
             }
             const v = styleValueFor(flat, key)
-            if (v !== undefined) styleResting[key] = v
+            // A static `style` may legitimately say `'transparent'`; the slot
+            // it seeds must not, or the next animation off that value dies.
+            if (v !== undefined) {
+              styleResting[key] = COLOR_KEY_SET.has(key)
+                ? normalizeAnimatableColor(v)
+                : v
+            }
           }
         }
       }
@@ -754,14 +780,13 @@ export function createMotionComponent<C extends ComponentType<any>>(
         boxShadowSeedRef.current =
           source !== undefined
             ? normalizeBoxShadow(source)
-            : (styleRestingShadow ?? {
-                layers: [...NO_BOX_SHADOW],
-                insets: null,
-              })
+            : (styleRestingShadow ?? { layers: [], insets: null })
       }
 
       const sharedValues = useAnimatableSharedValues((key) => {
-        if (key === 'boxShadow') return boxShadowSeedRef.current!.layers
+        if (key === 'boxShadow') {
+          return layersToPayload(boxShadowSeedRef.current!.layers)
+        }
         // Shadow offset synthetics seed from the corresponding axis on the
         // `shadowOffset: { width, height }` source — the consumer doesn't write
         // `shadowOffsetWidth` / `shadowOffsetHeight` directly. Fall back to the
@@ -788,16 +813,21 @@ export function createMotionComponent<C extends ComponentType<any>>(
             DEFAULT_RESTING[key]
           )
         }
+        // Colors are normalized on the way in: `initial` and `animate` are
+        // consumer strings and may say `'transparent'`, which Reanimated
+        // cannot animate *away from* (see `internal/color.ts`). The two
+        // fallbacks below are already normalized.
         if (initial === false) {
           const a = animateRecord[key]
-          return restValue(a) ?? styleResting[key] ?? DEFAULT_RESTING[key]
+          const seed = restValue(a) ?? styleResting[key] ?? DEFAULT_RESTING[key]
+          return COLOR_KEY_SET.has(key) ? normalizeAnimatableColor(seed) : seed
         }
-        return (
+        const seed =
           initialRecord?.[key] ??
           restValue(animateRecord[key]) ??
           styleResting[key] ??
           DEFAULT_RESTING[key]
-        )
+        return COLOR_KEY_SET.has(key) ? normalizeAnimatableColor(seed) : seed
       })
 
       // Keep never-driven keys tracking the *live* static style. The seed above
@@ -1014,8 +1044,17 @@ export function createMotionComponent<C extends ComponentType<any>>(
             isExiting ? onSettle : undefined,
             TRANSFORM_KEY_SET.has(key) ? transformGroup : undefined,
           )
+          // Normalized for the driver only, and after `targetEndValue` above:
+          // `onAnimationEnd` reports the target the consumer declared, not our
+          // rewriting of it. A color target of `'transparent'` animates fine
+          // — Reanimated dispatches on the *source* — but under
+          // `'no-animation'` (and so under reduced motion) it is assigned
+          // straight into the slot, and the next animation would start from a
+          // value that can't be parsed.
           sharedValues[key].value = resolveAnimatableValue(
-            target,
+            COLOR_KEY_SET.has(key)
+              ? normalizeAnimatableColorTarget(target)
+              : target,
             cfg,
             factory,
           ) as never
@@ -1243,17 +1282,19 @@ export function createMotionComponent<C extends ComponentType<any>>(
           out.shadowOffset = { width: shadowOffsetW, height: shadowOffsetH }
         }
         if (hasBoxShadow) {
-          const layers = sharedValues.boxShadow
-            .value as readonly AnimatedBoxShadowLayer[]
+          // The slot holds the layers keyed by index (Reanimated recurses into
+          // objects, not arrays — see `BoxShadowPayload`); RN wants an array,
+          // so this is where the two shapes meet.
+          const payload = sharedValues.boxShadow.value as BoxShadowPayload
           const insets = boxShadowInsets.value
-          // Fast path — no inset layer anywhere, so the animated array is
-          // already exactly what RN wants and crosses over untouched.
+          // Fast path — no inset layer anywhere, so each layer crosses over by
+          // reference and only the array itself is allocated.
           if (insets === null) {
-            out.boxShadow = layers
+            out.boxShadow = payloadToLayers(payload)
           } else {
             const withInset = []
-            for (let i = 0; i < layers.length; i++) {
-              withInset.push({ ...layers[i], inset: insets[i] })
+            for (let i = 0; payload[i] !== undefined; i++) {
+              withInset.push({ ...payload[i], inset: insets[i] })
             }
             out.boxShadow = withInset
           }
@@ -1486,6 +1527,13 @@ function makeKeyCallbackFactory(
     const reportedIteration = state.iteration
     if (phase === 'sequence' || phase === 'repeat') state.iteration++
 
+    // `boxShadow`'s slot is keyed by index so Reanimated will recurse into it;
+    // that is an internal shape, and the consumer gets the layer list.
+    const reportedValue =
+      key === 'boxShadow' && value !== undefined
+        ? payloadToLayers(value as BoxShadowPayload)
+        : value
+
     const fn = onAnimationEndRef.current
     if (fn) {
       // Transform-group coalescing: a multi-axis translate / scale /
@@ -1501,7 +1549,7 @@ function makeKeyCallbackFactory(
           fn({
             key: 'transform' as never,
             finished,
-            value,
+            value: reportedValue,
             target,
             phase,
             step,
@@ -1512,7 +1560,7 @@ function makeKeyCallbackFactory(
         fn({
           key: key as never,
           finished,
-          value,
+          value: reportedValue,
           target,
           phase,
           step,
@@ -1609,20 +1657,18 @@ function driveBoxShadow(
   cfg: TransitionConfig | undefined,
   factory: CallbackFactory | undefined,
 ): void {
-  const currentLayers = Array.isArray(slot.value)
-    ? (slot.value as readonly AnimatedBoxShadowLayer[])
-    : NO_BOX_SHADOW
+  const currentLayers = payloadToLayers(slot.value as BoxShadowPayload)
   const { from, to, insets } = prepareBoxShadowAnimation(
-    { layers: [...currentLayers], insets: insetSlot.value },
+    { layers: currentLayers, insets: insetSlot.value },
     target,
   )
   insetSlot.value = insets
-  if (from.length !== currentLayers.length) slot.value = from
+  if (from.length !== currentLayers.length) slot.value = layersToPayload(from)
   // `resolveTransition` is typed for the scalar surface it was written for;
   // Reanimated itself accepts the structured target and recurses into it.
   slot.value = resolveTransition(
     cfg,
-    to as unknown as number,
+    layersToPayload(to) as unknown as number,
     factory?.('animation', undefined),
   ) as AnimatableSlotValue
 }
@@ -1979,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
@@ -2015,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-67GHRCF6.js

@@ -1,8 +0,0 @@
-'use strict';
-
-var chunkVQ5D35UA_js = require('./chunk-VQ5D35UA.js');
-var reactNative = require('react-native');
-
-var MotionText = chunkVQ5D35UA_js.createMotionComponent(reactNative.Text);
-
-exports.MotionText = MotionText;

package/dist/chunk-GPOMFIIU.js

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

package/dist/chunk-K63LXGKS.js

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