@rootnative/inertia 0.0.3 → 0.0.5

package/src/internal/boxShadow.ts

@@ -144,17 +144,24 @@ export function parseBoxShadow(input: string): ResolvedBoxShadowLayer[] {
   })
 }
 
-/** Resolve either input form (CSS string or structured layers) to layers. */
+/**
+ * Resolve either input form (CSS string or structured layers) to layers.
+ *
+ * Lengths may arrive as numbers (what `useShadow`'s `BoxShadowLayer` declares)
+ * or as px strings (what RN's own `BoxShadowValue` permits, so what the
+ * `animate` surface has to accept). `coerceLength` normalizes both and rejects
+ * anything else, so downstream only ever sees concrete numbers.
+ */
 export function resolveBoxShadowInput(
-  input: string | readonly BoxShadowLayer[] | undefined,
+  input: BoxShadowInput | undefined,
 ): ResolvedBoxShadowLayer[] {
   if (input === undefined) return []
   if (typeof input === 'string') return parseBoxShadow(input)
   return input.map((layer) => ({
-    offsetX: layer.offsetX,
-    offsetY: layer.offsetY,
-    blurRadius: layer.blurRadius ?? 0,
-    spreadDistance: layer.spreadDistance ?? 0,
+    offsetX: coerceLength(layer.offsetX, 'offsetX'),
+    offsetY: coerceLength(layer.offsetY, 'offsetY'),
+    blurRadius: coerceLength(layer.blurRadius, 'blurRadius'),
+    spreadDistance: coerceLength(layer.spreadDistance, 'spreadDistance'),
     color: layer.color ?? 'black',
     inset: layer.inset ?? false,
   }))
@@ -202,3 +209,167 @@ function invisibleLayer(inset: boolean): ResolvedBoxShadowLayer {
     inset,
   }
 }
+
+/* ------------------------------------------------------------------ *
+ * Declarative `animate={{ boxShadow }}` support
+ *
+ * The `useShadow` path above interpolates two endpoints itself, by
+ * progress. The `animate` path instead hands the target to Reanimated's
+ * own animation drivers, which have their own rules — the helpers below
+ * exist to satisfy them on the JS thread so the worklet never does string
+ * or structural work at frame time (Principle 8).
+ * ------------------------------------------------------------------ */
+
+/**
+ * The interpolable half of a box-shadow layer: every field Reanimated can
+ * drive, and nothing it can't.
+ *
+ * `inset` is deliberately absent. `withTiming` / `withSpring` recurse into
+ * arrays and objects and animate each leaf, and a boolean leaf falls through
+ * to the plain numeric path — `false + (false - false) * p` evaluates to `0`,
+ * so an in-flight frame hands the native shadow a number where it expects a
+ * boolean. Inset is instead carried alongside as a static per-layer flag (see
+ * `SplitBoxShadow.insets`) and reattached when the style is emitted.
+ */
+export interface AnimatedBoxShadowLayer {
+  offsetX: number
+  offsetY: number
+  blurRadius: number
+  spreadDistance: number
+  color: string
+}
+
+/**
+ * Resolved layers split into the part Reanimated animates and the part it
+ * must not touch.
+ *
+ * `insets` is `null` — not an array of `false` — when no layer is inset, which
+ * is the overwhelmingly common case. That lets the emitting worklet skip
+ * reassembly entirely and pass the animated array straight through with zero
+ * per-frame allocation.
+ */
+export interface SplitBoxShadow {
+  layers: AnimatedBoxShadowLayer[]
+  insets: boolean[] | null
+}
+
+/**
+ * Accepted target shape on the `animate` surface: a CSS string or RN's own
+ * `BoxShadowValue[]`, whose lengths may be numbers or px strings.
+ *
+ * Structurally this is RN's `boxShadow` style value. It is restated here
+ * rather than imported so this module stays dependency-free and testable as a
+ * pure function; `types.ts` is where the public-facing alias lives.
+ */
+export type BoxShadowInput =
+  | string
+  | ReadonlyArray<{
+      offsetX: number | string
+      offsetY: number | string
+      // `unknown` because RN types this as `ColorValue | number` — a quirk of
+      // its own declarations rather than a real capability. Coerced (and
+      // rejected) by `coerceLength` like every other length.
+      blurRadius?: unknown
+      spreadDistance?: number | string | undefined
+      color?: string | undefined
+      inset?: boolean | undefined
+    }>
+
+/**
+ * Coerce one RN length field to a number. RN's `BoxShadowValue` types its
+ * lengths as `number | string` so `{ offsetX: '4px' }` is legal input; the
+ * animated slot needs a plain number to interpolate. Unit handling matches
+ * `parseBoxShadow` — px and unitless only, and anything else throws rather
+ * than silently animating from a `NaN`.
+ */
+function coerceLength(value: unknown, field: string): number {
+  if (value === undefined) return 0
+  if (typeof value === 'number') return value
+  const trimmed = typeof value === 'string' ? value.trim() : ''
+  if (!LENGTH.test(trimmed)) {
+    throw new Error(
+      `[inertia] boxShadow: ${field} must be a number or a px length, got ` +
+        `${JSON.stringify(value)}.`,
+    )
+  }
+  return parseFloat(trimmed)
+}
+
+/** Drop `inset`, leaving only the fields Reanimated may drive. */
+function strip(layer: ResolvedBoxShadowLayer): AnimatedBoxShadowLayer {
+  const { inset: _inset, ...rest } = layer
+  return rest
+}
+
+/**
+ * Record layer `i` as inset, materializing the flag list on first use so the
+ * common all-outset case keeps `null` and costs the worklet nothing.
+ */
+function markInset(
+  insets: boolean[] | null,
+  i: number,
+  count: number,
+): boolean[] {
+  const list = insets ?? new Array<boolean>(count).fill(false)
+  list[i] = true
+  return list
+}
+
+/**
+ * Normalize a target into the shared-value seed shape. Used when the slot is
+ * first populated (mount seed, static-style resting value).
+ */
+export function normalizeBoxShadow(input: BoxShadowInput): SplitBoxShadow {
+  const resolved = resolveBoxShadowInput(input)
+  const layers: AnimatedBoxShadowLayer[] = []
+  let insets: boolean[] | null = null
+  for (let i = 0; i < resolved.length; i++) {
+    const layer = resolved[i]!
+    layers.push(strip(layer))
+    if (layer.inset) insets = markInset(insets, i, resolved.length)
+  }
+  return { layers, insets }
+}
+
+/**
+ * Prepare a from/to pair for a Reanimated-driven `boxShadow` animation.
+ *
+ * Both sides come back padded to the same layer count, because Reanimated's
+ * `arrayOnStart` walks the **current** value's indices and reads `toValue[i]`
+ * for each — a target with fewer layers leaves the surplus leaves with
+ * `toValue: undefined`, and a target with more never animates the extras at
+ * all. `pairBoxShadowLayers` supplies the padding (a transparent zero layer,
+ * matching CSS transition semantics) and rejects a genuine inset mismatch.
+ *
+ * The returned `from` is only meaningful when it differs from what the slot
+ * already holds; callers snap the slot to it before starting the animation so
+ * the interpolation has a same-shaped base to run from.
+ */
+export function prepareBoxShadowAnimation(
+  current: SplitBoxShadow,
+  target: BoxShadowInput,
+): {
+  from: AnimatedBoxShadowLayer[]
+  to: AnimatedBoxShadowLayer[]
+  insets: boolean[] | null
+} {
+  const pairs = pairBoxShadowLayers(
+    current.layers.map((layer, i) => ({
+      ...layer,
+      inset: current.insets?.[i] ?? false,
+    })),
+    resolveBoxShadowInput(target),
+  )
+  const from: AnimatedBoxShadowLayer[] = []
+  const to: AnimatedBoxShadowLayer[] = []
+  let insets: boolean[] | null = null
+  for (let i = 0; i < pairs.length; i++) {
+    const pair = pairs[i]!
+    from.push(strip(pair.from))
+    to.push(strip(pair.to))
+    // `pairBoxShadowLayers` has already established that the two sides agree
+    // on inset, so reading either describes the pair.
+    if (pair.to.inset) insets = markInset(insets, i, pairs.length)
+  }
+  return { from, to, insets }
+}

package/src/internal/nonWorkletWarning.ts

@@ -1,3 +1,5 @@
+import { __resetWarnOnceForTests, warnOnce } from './warnOnce'
+
 declare const __DEV__: boolean
 
 // The core package intentionally has no Node types — declare the minimal
@@ -5,8 +7,6 @@ declare const __DEV__: boolean
 // 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
@@ -30,12 +30,10 @@ const warned = new Set<string>()
 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)
+  warnOnce(key, message)
 }
 
 /** @internal — test-only hook to reset the once-per-key state. */
 export function __resetNonWorkletWarningsForTests(): void {
-  warned.clear()
+  __resetWarnOnceForTests()
 }

package/src/internal/warnOnce.ts

@@ -0,0 +1,28 @@
+declare const __DEV__: boolean
+
+const warned = new Set<string>()
+
+/**
+ * Dev-only warning that fires at most once per `key` for the lifetime of the
+ * module.
+ *
+ * Inertia's warnings mostly fire from render or from a per-frame-adjacent
+ * resolver, so an unguarded `console.warn` would repeat on every render and
+ * bury the signal. Keying the guard (rather than using a single boolean)
+ * keeps two genuinely different misconfigurations from silencing each other.
+ *
+ * Unlike `warnNonWorkletOnce`, this is **not** suppressed under Jest — these
+ * warnings describe consumer-authored prop combinations, which a test suite
+ * should be able to assert on.
+ */
+export function warnOnce(key: string, message: string): void {
+  if (!__DEV__) 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 __resetWarnOnceForTests(): void {
+  warned.clear()
+}

package/src/layout/index.ts

@@ -8,10 +8,20 @@ export {
   SHARED_LAYOUT_TTL_MS,
   __setSharedLayoutClock,
   __sharedRegistrySize,
+  type CoordinateSpace,
+  type SharedLayoutSource,
   type SharedRect,
+  type SharedStyleSnapshot,
 } from './sharedRegistry'
+export {
+  __setSharedLayoutMeasurer,
+  measureWindowRect,
+  type MeasuredRect,
+  type WindowMeasurer,
+} from './measureWindow'
 export {
   useSharedLayout,
   type SharedLayoutBindings,
+  type SharedLayoutStyleValues,
   type SharedLayoutValues,
 } from './useSharedLayout'

package/src/layout/measureWindow.ts

@@ -0,0 +1,135 @@
+import { type CoordinateSpace, type SharedRect } from './sharedRegistry'
+
+/**
+ * Window-coordinate measurement for shared-element rects.
+ *
+ * ## Synchronous or not at all
+ *
+ * `measureInWindow` is callback-shaped but not reliably asynchronous, and the
+ * difference decides this module's design:
+ *
+ * - **Fabric** (the default from RN 0.76, and our 0.81+ baseline) resolves it
+ *   through a synchronous JSI call — the callback runs before
+ *   `measureInWindow` returns.
+ * - **Paper** goes over the bridge, so the callback lands a tick later.
+ * - **A detached node calls back never at all.** Not an edge case and not a
+ *   platform quirk: `ReactFabricHostComponent.measureInWindow` looks the node
+ *   up and simply returns when it is missing. The Jest host mock behaves the
+ *   same way.
+ *
+ * So this module reads the result **synchronously or treats it as
+ * unavailable**, and ignores a callback that arrives late. That is not a
+ * limitation to work around — it is what keeps the coordinate space coherent.
+ * An implementation that awaited the callback would put Fabric in window space
+ * and Paper in parent space *for the same element at different moments*, and
+ * since the two spaces aren't comparable, a source stored in one and a target
+ * measured in the other silently skips the transition. Better to be
+ * consistently parent-relative on a platform that can't measure synchronously —
+ * which is exactly how this worked before window coordinates existed.
+ *
+ * Net effect: nested-parent shared elements are fixed on Fabric, and on Paper
+ * the behavior is unchanged rather than intermittently broken.
+ *
+ * ## Why the result is validated rather than trusted
+ *
+ * A node that is off-screen or laid out to nothing reports zeros (or `NaN` on
+ * some platforms) instead of failing. Feeding that into a FLIP would fling the
+ * element in from the top-left corner — far worse than not animating. Anything
+ * unusable is reported as `undefined` so the caller falls back to the
+ * parent-relative rect it already has.
+ */
+
+/** Raw measurement, before it is tagged with a coordinate space. */
+export interface MeasuredRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/**
+ * Measures `node` in window coordinates, or returns `undefined` when it can't
+ * be measured synchronously. Swappable for tests via
+ * `__setSharedLayoutMeasurer`.
+ */
+export type WindowMeasurer = (node: unknown) => MeasuredRect | undefined
+
+type MeasureInWindowNode = {
+  measureInWindow?: (
+    callback: (x: number, y: number, width: number, height: number) => void,
+  ) => void
+}
+
+const defaultMeasurer: WindowMeasurer = (node) => {
+  const measure = (node as MeasureInWindowNode | null)?.measureInWindow
+  if (typeof measure !== 'function') return undefined
+
+  let result: MeasuredRect | undefined
+  let returned = false
+  try {
+    measure.call(node, (x, y, width, height) => {
+      // A callback that arrives after we've returned is Paper's asynchronous
+      // bridge answering too late to use. Dropping it is deliberate: accepting
+      // it would upgrade this element to window space while its counterpart
+      // stays parent-relative, and mixed spaces cancel the transition.
+      if (returned) return
+      result = { x, y, width, height }
+    })
+  } catch {
+    // Some hosts throw rather than no-op on a detached node.
+    returned = true
+    return undefined
+  }
+  returned = true
+  return result
+}
+
+let measurer: WindowMeasurer = defaultMeasurer
+
+function usable(rect: MeasuredRect): boolean {
+  const { x, y, width, height } = rect
+  for (const v of [x, y, width, height]) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) return false
+  }
+  // Zero-sized means "not really measurable" in practice — detached, or laid
+  // out to nothing. Either way there is no FLIP to compute from it.
+  return width !== 0 || height !== 0
+}
+
+/**
+ * Measure `node` in window coordinates and tag the result, or return
+ * `undefined` when no usable synchronous measurement is available.
+ *
+ * Validation lives here rather than in the default measurer so a swapped-in
+ * measurer is held to the same contract — an unusable rect can never reach a
+ * FLIP, however it was produced.
+ */
+export function measureWindowRect(node: unknown): SharedRect | undefined {
+  const measured = measurer(node)
+  if (!measured || !usable(measured)) return undefined
+  return toSharedRect(measured, 'window')
+}
+
+/** Tag a raw measurement with its coordinate space. */
+export function toSharedRect(
+  rect: MeasuredRect,
+  space: CoordinateSpace,
+): SharedRect {
+  return { ...rect, space }
+}
+
+/**
+ * Test hook: swap the measurement implementation. Pass `undefined` to restore
+ * the real `measureInWindow` path. Not exported from the package root —
+ * reachable only from inside the workspace.
+ *
+ * Needed because the Jest host mock's `measureInWindow` never invokes its
+ * callback, so without an override every test would exercise only the
+ * parent-relative fallback — which is also, deliberately, what a consumer's
+ * test suite sees.
+ */
+export function __setSharedLayoutMeasurer(
+  fn: WindowMeasurer | undefined,
+): void {
+  measurer = fn ?? defaultMeasurer
+}

package/src/layout/sharedRegistry.ts

@@ -1,6 +1,7 @@
 /**
- * Module-level registry of last-known on-screen rects for shared-layout
- * elements, indexed by `layoutId`. Backs `<Motion.* layoutId="..." />` —
+ * Module-level registry of last-known on-screen rects — and the style values
+ * the rect can't express — for shared-layout elements, indexed by `layoutId`.
+ * Backs `<Motion.* layoutId="..." />` —
  * Reanimated 4 dropped the `sharedTransitionTag` API the previous design
  * relied on, so the cross-screen shared-element transition lives in
  * userland now.
@@ -14,25 +15,86 @@
  *      it becomes the FLIP source rect; the entry is removed so a third
  *      mount with the same id doesn't re-animate from a stale snapshot.
  *
- * Rects are stored in **parent-relative coordinates** (what `onLayout`'s
- * `nativeEvent.layout` reports). This composes for the common case where the
- * source and target share an outer content container — e.g. a typical stack
- * navigator. Nested-parent setups, where the two parents sit at different
- * window offsets, need a window-coordinate path (`measureInWindow`); that is
- * punted to v2 per the roadmap.
+ * Rects are stored in **window coordinates** when the host node can be
+ * measured synchronously, and in the parent-relative coordinates `onLayout`
+ * reports when it can't (see `measureWindow.ts`). Which one an entry holds is
+ * recorded on the rect itself, because the two are not comparable: a FLIP
+ * computed from a parent-relative source against a window-space target is off
+ * by the parent's window offset. Consumers check the space and skip the
+ * animation rather than play a wrong one.
+ *
+ * Window coordinates are what make a shared element work when the source and
+ * target sit under containers at different screen offsets — the case the
+ * original parent-relative implementation got wrong. They cost something in
+ * return: `onLayout` does not fire when an *ancestor* scrolls, so a stored
+ * window rect goes stale as the user scrolls, where a parent-relative rect
+ * would not have. That is why an entry also carries `remeasure` while its
+ * owner is mounted; see `SharedLayoutSource`.
  */
 
-/** Parent-relative rect of a measured element (from `onLayout`). */
+/** Which coordinate system a rect's `x` / `y` are expressed in. */
+export type CoordinateSpace = 'window' | 'parent'
+
+/**
+ * The source element's values for the style keys a shared-element transition
+ * carries across (colors, `opacity`, `borderRadius`) — everything the rect
+ * FLIP can't express. Keys are `AnimatableKey`s, but typed loosely here so the
+ * registry stays independent of the factory's key vocabulary.
+ *
+ * Only keys the source actually had a value for appear. Absent means "the
+ * source had nothing to say about this" — the target then keeps its own value
+ * rather than crossfading from an invented one.
+ */
+export type SharedStyleSnapshot = Record<string, number | string>
+
+/** Measured rect of an element, tagged with its coordinate space. */
 export interface SharedRect {
   x: number
   y: number
   width: number
   height: number
+  space: CoordinateSpace
+}
+
+/**
+ * What `consumeLayout` hands back: the last recorded rect, plus — only while
+ * the source element is *still mounted* — a way to ask it for a fresh one.
+ *
+ * The re-measure hook is what keeps window coordinates honest in the dominant
+ * case. In a stack navigator the source screen stays mounted underneath the
+ * pushed one, so at the moment the target first lays out the source is still
+ * there and can be measured *now* rather than trusted from whenever its last
+ * layout happened. Without it, scrolling a list before tapping a row would
+ * offset every shared-element transition by the scroll distance.
+ *
+ * Returns `undefined` when the source can no longer be measured, in which case
+ * the caller keeps the stored rect. Absent entirely once `releaseLayout` has
+ * run, since by then there is no node left to measure.
+ */
+export interface SharedLayoutSource {
+  rect: SharedRect
+  remeasure?: () => SharedRect | undefined
+  /**
+   * The source's carried style values, as of its last layout. Present only
+   * once `releaseLayout` has run — while the owner is still mounted,
+   * `readStyles` supersedes this for the same reason `remeasure` supersedes
+   * the stored rect.
+   */
+  styles?: SharedStyleSnapshot
+  /**
+   * Read the source's carried style values *now*. Offered only while the
+   * source is mounted. Its values move without a layout pass (an animation
+   * settling, a theme swap), so a stored snapshot is a floor, not the truth.
+   */
+  readStyles?: () => SharedStyleSnapshot | undefined
 }
 
 interface Entry {
   rect: SharedRect
   expiresAt: number
+  remeasure?: () => SharedRect | undefined
+  styles?: SharedStyleSnapshot
+  readStyles?: () => SharedStyleSnapshot | undefined
 }
 
 const REGISTRY = new Map<string, Entry>()
@@ -87,37 +149,64 @@ function sweepExpired(at: number): void {
  * Motion primitive with `layoutId` set so the registry always holds a
  * current measurement if that primitive becomes the source of a future
  * transition. Resets the TTL each call.
+ *
+ * `remeasure` and `readStyles` are the still-mounted owner's offer to be read
+ * again on demand — pass them while the element is live so a consumer can
+ * prefer fresh values over whatever this call recorded.
  */
-export function registerLayout(id: string, rect: SharedRect): void {
+export function registerLayout(
+  id: string,
+  rect: SharedRect,
+  remeasure?: () => SharedRect | undefined,
+  readStyles?: () => SharedStyleSnapshot | undefined,
+): void {
   const at = now()
   sweepExpired(at)
-  REGISTRY.set(id, { rect, expiresAt: at + SHARED_LAYOUT_TTL_MS })
+  REGISTRY.set(id, {
+    rect,
+    expiresAt: at + SHARED_LAYOUT_TTL_MS,
+    remeasure,
+    readStyles,
+  })
 }
 
 /**
  * Record the rect for `id` on unmount so the next mount can consume it as
- * the FLIP source. Functionally identical to `registerLayout` — the split
- * is purely intent-documenting at the call site.
+ * the FLIP source.
+ *
+ * Deliberately drops any `remeasure` / `readStyles` hook the mounted entry
+ * carried: the node is on its way out, and measuring a detached view yields
+ * zeros. From here the values recorded by this call are all a consumer gets —
+ * which is why `styles` is passed by value here and by callback above.
  */
-export function releaseLayout(id: string, rect: SharedRect): void {
+export function releaseLayout(
+  id: string,
+  rect: SharedRect,
+  styles?: SharedStyleSnapshot,
+): void {
   const at = now()
   sweepExpired(at)
-  REGISTRY.set(id, { rect, expiresAt: at + SHARED_LAYOUT_TTL_MS })
+  REGISTRY.set(id, { rect, expiresAt: at + SHARED_LAYOUT_TTL_MS, styles })
 }
 
 /**
- * Take the recorded rect for `id` if it exists and hasn't expired. The
+ * Take the recorded source for `id` if it exists and hasn't expired. The
  * entry is removed in either case — at most one incoming mount consumes
  * a given release, and an expired entry is dropped so it can't poison a
  * later transition. Returns `undefined` when no fresh source is available,
  * in which case the caller should mount without a layout animation.
  */
-export function consumeLayout(id: string): SharedRect | undefined {
+export function consumeLayout(id: string): SharedLayoutSource | undefined {
   const entry = REGISTRY.get(id)
   if (!entry) return undefined
   REGISTRY.delete(id)
   if (entry.expiresAt < now()) return undefined
-  return entry.rect
+  return {
+    rect: entry.rect,
+    remeasure: entry.remeasure,
+    styles: entry.styles,
+    readStyles: entry.readStyles,
+  }
 }
 
 /** Drop all entries. Tests use this to isolate between cases. */