@rootnative/inertia 0.0.0-alpha.4 → 0.0.0-alpha.6

package/src/internal/nonWorkletWarning.ts

@@ -0,0 +1,41 @@
+declare const __DEV__: boolean
+
+// The core package intentionally has no Node types — declare the minimal
+// shape needed for the Jest detection below (guarded by a typeof check, so
+// environments without `process` are fine).
+declare const process: { env?: Record<string, string | undefined> } | undefined
+
+const warned = new Set<string>()
+
+/**
+ * Dev-only, once-per-key warning for plain (non-worklet) functions handed to
+ * surfaces that need real worklets — `useTransform` transformers and custom
+ * `timing.easing` functions.
+ *
+ * Why this can't be papered over with an auto-wrap: wrapping a plain
+ * function in a `'worklet'`-directive closure captures the *function
+ * reference*, not the shared values it reads. Even when the consumer's
+ * Babel plugin workletizes the wrapper, its `__closure` contains only the
+ * opaque JS function — Reanimated cannot extract the shared values read
+ * inside it as dependencies (so derived values never refresh), and native
+ * builds reject the plain function when the closure is serialized to the UI
+ * thread. The only correct authoring is the `'worklet'` directive on the
+ * consumer's own function, where *their* Babel pass captures the real
+ * closure.
+ *
+ * Suppressed under Jest: the shared Reanimated/worklets test stubs report
+ * every function as non-worklet, which would turn the warning into noise in
+ * every consumer's test suite.
+ */
+export function warnNonWorkletOnce(key: string, message: string): void {
+  if (!__DEV__) return
+  if (typeof process !== 'undefined' && process.env?.JEST_WORKER_ID) return
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(message)
+}
+
+/** @internal — test-only hook to reset the once-per-key state. */
+export function __resetNonWorkletWarningsForTests(): void {
+  warned.clear()
+}

package/src/layout/resolveLayout.ts

@@ -13,8 +13,9 @@ export type LayoutProp = boolean | TransitionConfig | undefined
  * - `true` → default spring with the library's tuned tension / friction / mass.
  * - `{ type: 'spring', ... }` → spring with react-spring vocabulary, bridged
  *   into `springify().damping().stiffness().mass()` via `springToReanimated`.
- * - `{ type: 'timing', ... }` → `.duration().easing()`. User easing fns are
- *   auto-wrapped as worklets (Reanimated 3.9+ validates this).
+ * - `{ type: 'timing', ... }` → `.duration().easing()`. Custom easing fns
+ *   must be worklets (Reanimated 3.9+ validates this); plain functions
+ *   dev-warn via `ensureWorkletEasing`.
  * - `{ type: 'decay', ... }` → silently downgrades to spring; decay doesn't
  *   have a clear target for a layout transition.
  *

package/src/transitions/easing.ts

@@ -1,20 +1,21 @@
 // `isWorkletFunction` lives in `react-native-worklets` (the Reanimated 4 peer
 // dep); Reanimated's own re-export is deprecated.
 import { isWorkletFunction } from 'react-native-worklets'
+import { warnNonWorkletOnce } from '../internal/nonWorkletWarning'
 import { type EasingInput } from '../types'
 
 /**
  * Reanimated 3.9+ validates that easing functions used in nested-transition
  * contexts (variants, sequences, per-property maps) are worklets, and crashes
- * with `[Reanimated] The easing function is not a worklet` otherwise. The
- * library accepts plain functions on the public surface; this helper wraps
- * them so consumers don't have to think about the worklet boundary.
+ * with `[Reanimated] The easing function is not a worklet` otherwise.
  *
- * If the input is already a worklet (has been processed by the worklets babel
- * plugin), it's returned as-is. Otherwise it's wrapped in a function whose
- * body declares the `'worklet'` directive — when our source is processed by
- * the consumer's worklets babel plugin (the default Expo/RN setup), the
- * wrapper becomes a real worklet that captures the user fn via closure.
+ * Custom easing functions MUST therefore be worklets — put the `'worklet'`
+ * directive as the function's first statement (Reanimated's built-in
+ * `Easing.*` helpers and inertia's `cubicBezier()` already are). A plain
+ * function warns in dev and falls back to a directive-wrapped call-through;
+ * that wrapper works on web (single-threaded) but its closure holds the
+ * opaque plain function, which native builds reject when the transition's
+ * config is serialized to the UI thread.
  *
  * Reanimated 4 changed `Easing.bezier(...)` to return an
  * `EasingFunctionFactory` (`{ factory: () => EasingFunction }`) rather than
@@ -34,6 +35,10 @@ export function ensureWorkletEasing(
   // ends up in the transition config.
   const fn = isEasingFactory(easing) ? easing.factory() : easing
   if (isWorkletFunction(fn)) return fn
+  warnNonWorkletOnce(
+    'timing-easing',
+    "[inertia] timing easing: the provided easing function is not a worklet. The fallback wrapper works on web but native builds reject it when the transition runs on the UI thread. Add the 'worklet' directive as the first statement of the easing function, or use Reanimated's Easing.* helpers / inertia's cubicBezier(), which are already worklets.",
+  )
   const wrapped = (t: number) => {
     'worklet'
     return fn(t)

package/src/values/index.ts

@@ -20,6 +20,7 @@ export {
 export { useScroll, type UseScrollResult } from './useScroll'
 export {
   useShadow,
+  type BoxShadowLayer,
   type ShadowConfig,
   type UseShadowOptions,
 } from './useShadow'

package/src/values/useShadow.ts

@@ -4,12 +4,20 @@ import {
   useAnimatedStyle,
   type SharedValue,
 } from 'react-native-reanimated'
+import {
+  pairBoxShadowLayers,
+  resolveBoxShadowInput,
+  type BoxShadowLayer,
+} from '../internal/boxShadow'
+
+export type { BoxShadowLayer }
 
 /**
  * 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.
+ * surface, plus the nested `shadowOffset` source and the CSS `boxShadow`
+ * surface.
  */
 export interface ShadowConfig {
   shadowOpacity?: number
@@ -18,6 +26,19 @@ export interface ShadowConfig {
   /** Android elevation. iOS shadow consumers can leave this off. */
   elevation?: number
   shadowColor?: string
+  /**
+   * CSS `box-shadow` — the shadow surface on web (react-native-web passes
+   * it through as CSS) and on React Native 0.76+ new-architecture native.
+   * Accepts the CSS string form design systems store elevation tokens in
+   * (`'0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'`;
+   * px lengths only) or structured layers. Multi-layer shadows interpolate
+   * per layer; when one side has fewer layers, it is padded with invisible
+   * layers, CSS-transition style. A malformed string **throws** at render
+   * (like `cubicBezier` — token mistakes should fail loudly at setup).
+   * The classic `shadow*`/`elevation` keys don't reach the web renderer —
+   * provide `boxShadow` alongside them when the tween must show up there.
+   */
+  boxShadow?: string | readonly BoxShadowLayer[]
 }
 
 export interface UseShadowOptions {
@@ -56,6 +77,19 @@ export interface UseShadowOptions {
  * `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.
+ *
+ * The classic `shadow*`/`elevation` keys don't render on web. When the
+ * tween must show up there (or on RN 0.76+ new-arch native via the CSS
+ * shadow model), provide `boxShadow` on both ends — CSS string tokens or
+ * structured layers; multi-layer shadows interpolate per layer:
+ *
+ * ```tsx
+ * const shadowStyle = useShadow({
+ *   from: { boxShadow: theme.elevation.level1 }, // '0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)'
+ *   to:   { boxShadow: theme.elevation.level2 },
+ *   progress,
+ * })
+ * ```
  */
 export function useShadow({
   from,
@@ -76,6 +110,17 @@ export function useShadow({
   const hasOffset =
     from.shadowOffset !== undefined || to.shadowOffset !== undefined
 
+  // boxShadow layers: parse/pair once on the JS thread into flat records so
+  // the worklet only interpolates numbers/colors and concatenates — no
+  // frame-time parsing. `[]` when neither side provides the key.
+  const boxShadowPairs =
+    from.boxShadow !== undefined || to.boxShadow !== undefined
+      ? pairBoxShadowLayers(
+          resolveBoxShadowInput(from.boxShadow),
+          resolveBoxShadowInput(to.boxShadow),
+        )
+      : []
+
   const opacityFrom = from.shadowOpacity ?? 0
   const opacityTo = to.shadowOpacity ?? 0
   const radiusFrom = from.shadowRadius ?? 0
@@ -111,6 +156,36 @@ export function useShadow({
         height: interpolate(t, [0, 1], [offsetHFrom, offsetHTo]),
       }
     }
+    if (boxShadowPairs.length > 0) {
+      let css = ''
+      let first = true
+      for (const pair of boxShadowPairs) {
+        const x = interpolate(t, [0, 1], [pair.from.offsetX, pair.to.offsetX])
+        const y = interpolate(t, [0, 1], [pair.from.offsetY, pair.to.offsetY])
+        // Blur can't go negative (invalid CSS) even if a springy driver
+        // overshoots below 0.
+        const blur = Math.max(
+          0,
+          interpolate(t, [0, 1], [pair.from.blurRadius, pair.to.blurRadius]),
+        )
+        const spread = interpolate(
+          t,
+          [0, 1],
+          [pair.from.spreadDistance, pair.to.spreadDistance],
+        )
+        const color = interpolateColor(
+          t,
+          [0, 1],
+          [pair.from.color, pair.to.color],
+        )
+        css +=
+          (first ? '' : ', ') +
+          (pair.from.inset ? 'inset ' : '') +
+          `${x}px ${y}px ${blur}px ${spread}px ${color}`
+        first = false
+      }
+      out.boxShadow = css
+    }
     return out
   })
 }

package/src/values/useTransform.ts

@@ -10,6 +10,7 @@ import {
 // `react-native-worklets` is a required peer of Reanimated 4, so the direct
 // import is always available wherever Inertia is.
 import { isWorkletFunction } from 'react-native-worklets'
+import { warnNonWorkletOnce } from '../internal/nonWorkletWarning'
 
 /**
  * Extrapolation behavior at the edges of the input range. Mirrors
@@ -36,9 +37,17 @@ export interface UseTransformOptions {
  * const distance = useTransform(() => Math.sqrt(x.value ** 2 + y.value ** 2))
  * ```
  *
- * The transformer must be a worklet (or a plain function we auto-wrap —
- * see the easing wrapper for the rationale). It runs on the UI thread on
- * every frame where any read shared value changes.
+ * The transformer MUST be a worklet — put the `'worklet'` directive as its
+ * first statement so the consumer's Babel plugin captures the shared values
+ * it reads as its closure. It runs on the UI thread on every frame where
+ * any read shared value changes.
+ *
+ * A plain function cannot work here, and the hook warns in dev when it gets
+ * one: the best-effort wrapper it falls back to closes over the opaque
+ * function reference, not the shared values read inside it, so Reanimated
+ * can't track them as dependencies — the derived value only refreshes on
+ * React re-renders, and native builds reject the plain function when the
+ * closure crosses to the UI thread.
  */
 export function useTransform<T>(transformer: () => T): SharedValue<T>
 
@@ -80,16 +89,23 @@ export function useTransform<T>(
   // interpolation) is decided once at JS time, never at frame time.
   let producer: () => unknown
   if (typeof arg1 === 'function') {
-    // Transformer overload. The public surface accepts a plain function;
-    // Reanimated 3.9+ requires worklets in nested-derivation contexts, so
-    // we auto-wrap at JS time the same way `ensureWorkletEasing` does.
+    // Transformer overload. Must be a worklet — the directive-wrapped
+    // fallback below is best-effort only (its closure holds the opaque
+    // function, not the shared values read inside it, so dependency
+    // tracking cannot work — see `warnNonWorkletOnce`).
     const userFn = arg1 as () => T
-    producer = isWorkletFunction(userFn)
-      ? userFn
-      : () => {
-          'worklet'
-          return userFn()
-        }
+    if (isWorkletFunction(userFn)) {
+      producer = userFn
+    } else {
+      warnNonWorkletOnce(
+        'useTransform-transformer',
+        "[inertia] useTransform: the transformer is not a worklet, so the shared values it reads can't be tracked as dependencies — the derived value will only refresh on React re-renders, and native builds reject plain functions on the UI thread. Add the 'worklet' directive as the first statement of the transformer.",
+      )
+      producer = () => {
+        'worklet'
+        return userFn()
+      }
+    }
   } else {
     // Interpolation overload. We pre-resolve everything JS-side so the
     // worklet body only consumes flat values.

package/dist/chunk-NDKVHL3N.js

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

package/dist/chunk-SCTX5Z7I.js

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

package/dist/chunk-WZGMAXKC.js

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