@onlynative/inertia 0.0.1-alpha.7 → 0.0.1-alpha.9

package/src/__type-tests__/variants.test-d.tsx

@@ -0,0 +1,67 @@
+/**
+ * Compile-time gate for variant-key narrowing on `animate`.
+ *
+ * CLAUDE.md Principle 5 / line 43: "Variant string keys must autocomplete on
+ * `animate`." That requires the `variants` map to be inferred at the JSX call
+ * site and `animate`'s string form to be narrowed to its keys — so a key typo
+ * is a type error, not a silent runtime no-op. These assertions run under
+ * `tsc --noEmit` (the typecheck CI step); if a `@ts-expect-error` here stops
+ * being an error, tsc fails with "Unused '@ts-expect-error' directive" and the
+ * differentiator has regressed.
+ *
+ * Unlike `animate.test-d.tsx`, these MUST mount JSX: the narrowing depends on
+ * `V` being inferred from the `variants` prop at the call site, which only
+ * happens through the generic component call signature.
+ */
+
+import { Motion } from '../motion'
+
+const variants = {
+  open: { opacity: 1, translateY: 0 },
+  closed: { opacity: 0, translateY: 100 },
+} as const
+
+// ─── Variant key narrowing ──────────────────────────────────────────────────
+
+// A declared key is accepted (and `open` / `closed` autocomplete here).
+const _acceptsKnownKey = <Motion.View variants={variants} animate="open" />
+const _acceptsOtherKey = <Motion.View variants={variants} animate="closed" />
+
+// A typo'd key is a compile error rather than a silent no-op.
+// @ts-expect-error 'opne' is not a key of `variants`
+const _rejectsTypoKey = <Motion.View variants={variants} animate="opne" />
+
+// The style-object form still works alongside `variants` (escape hatch for a
+// one-off target that isn't a named state).
+const _acceptsStyleObject = (
+  <Motion.View variants={variants} animate={{ opacity: 0.5 }} />
+)
+
+// `as const` is NOT required — an inline object literal narrows just as well.
+const inlineVariants = { a: { opacity: 1 }, b: { opacity: 0 } }
+const _inlineVariantsNarrow = (
+  <Motion.View variants={inlineVariants} animate="a" />
+)
+const _inlineVariantsReject = (
+  // @ts-expect-error 'c' is not a key of the inline variants map
+  <Motion.View variants={inlineVariants} animate="c" />
+)
+
+// ─── No variants → string stays open (back-compat) ──────────────────────────
+
+// Without `variants`, the string form is unconstrained, so this must NOT error
+// (the variant-less call site is unchanged by the narrowing machinery).
+const _noVariantsAnyString = <Motion.View animate="whatever" />
+const _noVariantsStyleObject = <Motion.View animate={{ translateX: 10 }} />
+
+// Silence "declared but never read" — these exist purely as type assertions.
+export type _VariantTypeAssertions = [
+  typeof _acceptsKnownKey,
+  typeof _acceptsOtherKey,
+  typeof _rejectsTypoKey,
+  typeof _acceptsStyleObject,
+  typeof _inlineVariantsNarrow,
+  typeof _inlineVariantsReject,
+  typeof _noVariantsAnyString,
+  typeof _noVariantsStyleObject,
+]

package/src/gestureLayer/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Opt-in subpath: `@onlynative/inertia/gesture-layer`.
+ *
+ * `useGestureLayer` is a generic interactive-feedback primitive that sits one
+ * step above `useGesture()` — consumer supplies per-state target values; the
+ * hook handles "strongest active layer wins" composition (clamped-max for
+ * numerics, priority cascade for colors), the worklet, and the transition.
+ *
+ * Reach for it when MD3 state-layer haloes, iOS-translucent overlays, or
+ * any "highest engaged state controls the overlay" pattern shows up. For
+ * composition models this hook doesn't express (additive, multiply, custom
+ * per-key blends), drop to `useGesture()` and write a `useAnimatedStyle`
+ * block by hand.
+ */
+export { useGestureLayer } from './useGestureLayer'
+export type {
+  GestureLayerStates,
+  GestureLayerStyle,
+  UseGestureLayerOptions,
+  UseGestureLayerResult,
+} from './useGestureLayer'

package/src/gestureLayer/useGestureLayer.ts

@@ -0,0 +1,285 @@
+import { useEffect, useMemo } from 'react'
+import {
+  interpolateColor,
+  useAnimatedStyle,
+  useSharedValue,
+  type AnimatedStyle,
+} from 'react-native-reanimated'
+import { useShouldReduceMotion } from '../config'
+import { isTopLevelTransition, resolveTransition } from '../transitions'
+import { useGesture, type UseGestureHandlers } from '../values/useGesture'
+import { type GestureLayerTransitions, type TransitionConfig } from '../types'
+
+/**
+ * A single gesture-layer style — a flat map of style keys to a value. Numeric
+ * values participate in clamped-max composition (the "strongest active layer
+ * wins" model used by MD3 state-layer haloes); string values are treated as
+ * colors and composed via priority cascade with `interpolateColor`.
+ *
+ * The hook does not validate that string values are valid colors — passing
+ * something like `borderStyle: 'solid'` will crash inside the worklet. Keep
+ * string values to color strings.
+ */
+export type GestureLayerStyle = {
+  [key: string]: number | string | undefined
+}
+
+/**
+ * Per-state style maps. Every key is optional; missing layers default to
+ * `rest` (or `0` / `'transparent'` if `rest` is also absent for that key).
+ *
+ * - `rest` — base values, applied when no other layer is active.
+ * - `hovered` / `focused` / `focusVisible` / `pressed` — gesture-driven
+ *   states tracked via the underlying `useGesture` hook. Each owns an
+ *   independent 0↔1 progress that fades the layer in/out per the configured
+ *   transition.
+ * - `disabled` — gated by the JS-side `options.disabled` flag rather than a
+ *   gesture. Sits at the top of the priority cascade and overrides every
+ *   gesture layer when active.
+ */
+export interface GestureLayerStates {
+  rest?: GestureLayerStyle
+  hovered?: GestureLayerStyle
+  focused?: GestureLayerStyle
+  focusVisible?: GestureLayerStyle
+  pressed?: GestureLayerStyle
+  disabled?: GestureLayerStyle
+}
+
+export interface UseGestureLayerOptions {
+  /**
+   * When `true`, the `disabled` layer becomes active (or `rest` if `disabled`
+   * is undefined). Animates via the top-level transition or the library
+   * default spring; per-layer transitions (`GestureLayerTransitions`) do not
+   * apply to `disabled`.
+   */
+  disabled?: boolean
+  /**
+   * 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`.
+   */
+  transition?: TransitionConfig | GestureLayerTransitions
+}
+
+export interface UseGestureLayerResult {
+  /**
+   * Animated style produced by `useAnimatedStyle` — spread on an
+   * `Animated.View` or pass through `<Motion.View style={...} />`.
+   */
+  style: AnimatedStyle<Record<string, unknown>>
+  /** Handlers to spread on the receiving `Pressable`. */
+  handlers: UseGestureHandlers
+}
+
+/**
+ * A "strongest active layer wins" interactive-feedback primitive. Sits one
+ * step above `useGesture()` — the consumer supplies the per-state target
+ * values, the hook handles the four gesture progress shared values, the
+ * disabled override, the worklet, and the transition.
+ *
+ * Composition model:
+ *
+ * - **Numeric keys** (opacity, scale, borderWidth, etc.) compose via
+ *   clamped-max with `rest` as the floor:
+ *   `out = max(rest, ...for each active gesture layer: lerp(rest, layer, progress))`.
+ *   This matches the MD3 state-layer halo pattern — multiple states active
+ *   simultaneously raise the value to the strongest, not the sum.
+ * - **Color keys** (any string value) compose via priority cascade with
+ *   `interpolateColor`, lowest priority first: `hovered → focused →
+ *   focusVisible → pressed`. Clamped-max doesn't apply to colors; this
+ *   matches the cascade used by the declarative `gesture` prop.
+ * - **Disabled** sits at the top of the cascade for both numeric and color
+ *   keys — when active, it lerps the composed value toward the `disabled`
+ *   target.
+ *
+ * Reach for this when you want MD3 / iOS-translucent state-layer overlays
+ * without rewriting the worklet by hand for every consumer; reach for plain
+ * `useGesture()` when you need a composition model this hook doesn't
+ * express (additive, multiply, per-key custom blends).
+ *
+ * @example MD3 state-layer halo
+ * ```tsx
+ * import { useGestureLayer } from '@onlynative/inertia/gesture-layer'
+ * import Animated from 'react-native-reanimated'
+ * import { Pressable } from 'react-native'
+ *
+ * function SwitchHalo({ disabled }: { disabled?: boolean }) {
+ *   const { style, handlers } = useGestureLayer(
+ *     {
+ *       rest: { opacity: 0, backgroundColor: 'transparent' },
+ *       hovered: { opacity: 0.08, backgroundColor: '#000' },
+ *       focused: { opacity: 0.10, backgroundColor: '#000' },
+ *       pressed: { opacity: 0.12, backgroundColor: '#000' },
+ *     },
+ *     { disabled, transition: { type: 'timing', duration: 150 } },
+ *   )
+ *
+ *   return (
+ *     <Pressable {...handlers}>
+ *       <Animated.View style={style} />
+ *     </Pressable>
+ *   )
+ * }
+ * ```
+ */
+export function useGestureLayer(
+  states: GestureLayerStates,
+  options: UseGestureLayerOptions = {},
+): UseGestureLayerResult {
+  const { disabled: isDisabled = false, transition } = options
+  const shouldReduceMotion = useShouldReduceMotion()
+  const gesture = useGesture(transition)
+  const disabledProgress = useSharedValue(0)
+
+  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])
+
+  // JS-thread precompute: union of keys across all layers, per-key type
+  // (number vs color), and a rest-fallback table. The worklet body reads
+  // from `meta` instead of probing each layer per frame — the type check
+  // only runs when layer identities change.
+  const meta = useMemo(() => {
+    const layers = {
+      rest: states.rest,
+      hovered: states.hovered,
+      focused: states.focused,
+      focusVisible: states.focusVisible,
+      pressed: states.pressed,
+      disabled: states.disabled,
+    }
+    const sources = [
+      layers.rest,
+      layers.hovered,
+      layers.focused,
+      layers.focusVisible,
+      layers.pressed,
+      layers.disabled,
+    ]
+    const keySet = new Set<string>()
+    for (const src of sources) {
+      if (!src) continue
+      for (const k in src) if (src[k] !== undefined) keySet.add(k)
+    }
+    const keys = Array.from(keySet)
+    const types: Record<string, 'number' | 'color'> = {}
+    const restValues: Record<string, number | string> = {}
+    for (const k of keys) {
+      let firstDefined: number | string | undefined
+      for (const src of sources) {
+        if (src && src[k] !== undefined) {
+          firstDefined = src[k]
+          break
+        }
+      }
+      const isColor = typeof firstDefined === 'string'
+      types[k] = isColor ? 'color' : 'number'
+      const restRaw = layers.rest ? layers.rest[k] : undefined
+      restValues[k] =
+        restRaw !== undefined ? restRaw : isColor ? 'transparent' : 0
+    }
+    return { layers, keys, types, restValues }
+  }, [
+    states.rest,
+    states.hovered,
+    states.focused,
+    states.focusVisible,
+    states.pressed,
+    states.disabled,
+  ])
+
+  const style = useAnimatedStyle(() => {
+    const { layers, keys, types, restValues } = meta
+    const ph = gesture.hovered.value
+    const pf = gesture.focused.value
+    const pfv = gesture.focusVisible.value
+    const pp = gesture.pressed.value
+    const pd = disabledProgress.value
+
+    const hoveredLayer = layers.hovered
+    const focusedLayer = layers.focused
+    const focusVisibleLayer = layers.focusVisible
+    const pressedLayer = layers.pressed
+    const disabledLayer = layers.disabled
+
+    const out: Record<string, unknown> = {}
+
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i]!
+      const isColor = types[k] === 'color'
+      const rest = restValues[k]!
+
+      if (isColor) {
+        let v = rest as string
+        if (hoveredLayer && ph > 0 && hoveredLayer[k] !== undefined) {
+          v = interpolateColor(ph, [0, 1], [v, hoveredLayer[k] as string])
+        }
+        if (focusedLayer && pf > 0 && focusedLayer[k] !== undefined) {
+          v = interpolateColor(pf, [0, 1], [v, focusedLayer[k] as string])
+        }
+        if (
+          focusVisibleLayer &&
+          pfv > 0 &&
+          focusVisibleLayer[k] !== undefined
+        ) {
+          v = interpolateColor(pfv, [0, 1], [v, focusVisibleLayer[k] as string])
+        }
+        if (pressedLayer && pp > 0 && pressedLayer[k] !== undefined) {
+          v = interpolateColor(pp, [0, 1], [v, pressedLayer[k] as string])
+        }
+        if (disabledLayer && pd > 0 && disabledLayer[k] !== undefined) {
+          v = interpolateColor(pd, [0, 1], [v, disabledLayer[k] as string])
+        }
+        out[k] = v
+      } else {
+        const base = rest as number
+        let m = base
+        if (hoveredLayer && ph > 0 && hoveredLayer[k] !== undefined) {
+          const c = base + ((hoveredLayer[k] as number) - base) * ph
+          if (c > m) m = c
+        }
+        if (focusedLayer && pf > 0 && focusedLayer[k] !== undefined) {
+          const c = base + ((focusedLayer[k] as number) - base) * pf
+          if (c > m) m = c
+        }
+        if (
+          focusVisibleLayer &&
+          pfv > 0 &&
+          focusVisibleLayer[k] !== undefined
+        ) {
+          const c = base + ((focusVisibleLayer[k] as number) - base) * pfv
+          if (c > m) m = c
+        }
+        if (pressedLayer && pp > 0 && pressedLayer[k] !== undefined) {
+          const c = base + ((pressedLayer[k] as number) - base) * pp
+          if (c > m) m = c
+        }
+        if (disabledLayer && pd > 0 && disabledLayer[k] !== undefined) {
+          m = m + ((disabledLayer[k] as number) - m) * pd
+        }
+        out[k] = m
+      }
+    }
+
+    return out
+  })
+
+  return {
+    style: style as AnimatedStyle<Record<string, unknown>>,
+    handlers: gesture.handlers,
+  }
+}
+
+function disabledTransition(
+  transition: TransitionConfig | GestureLayerTransitions | undefined,
+): TransitionConfig | undefined {
+  if (!transition) return undefined
+  if (isTopLevelTransition(transition)) return transition
+  return undefined
+}

package/src/index.ts

@@ -30,18 +30,25 @@ export {
 } from './transitions'
 export {
   useAnimation,
+  useBooleanSpring,
+  useColorTransition,
   useGesture,
   useMotionValue,
   useScroll,
+  useShadow,
   useSpring,
   useTransform,
   useVariants,
 } from './values'
 export type {
+  ColorStyleKey,
   ExtrapolationMode,
+  ShadowConfig,
+  UseColorTransitionOptions,
   UseGestureHandlers,
   UseGestureResult,
   UseScrollResult,
+  UseShadowOptions,
   UseTransformOptions,
 } from './values'
 export type {

package/src/layout/index.ts

@@ -1 +1,16 @@
 export { resolveLayoutTransition, type LayoutProp } from './resolveLayout'
+export {
+  clearSharedRegistry,
+  consumeLayout,
+  peekSharedLayout,
+  registerLayout,
+  releaseLayout,
+  SHARED_LAYOUT_TTL_MS,
+  __setSharedLayoutClock,
+  type SharedRect,
+} from './sharedRegistry'
+export {
+  useSharedLayout,
+  type SharedLayoutBindings,
+  type SharedLayoutValues,
+} from './useSharedLayout'

package/src/layout/sharedRegistry.ts

@@ -0,0 +1,111 @@
+/**
+ * Module-level registry of last-known on-screen rects 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.
+ *
+ * Lifecycle, per id:
+ *   1. While a Motion primitive with `layoutId={id}` is mounted, every
+ *      `onLayout` updates the rect via `registerLayout`.
+ *   2. When that primitive unmounts, the same rect is left behind under a
+ *      TTL via `releaseLayout` so a subsequent mount can consume it.
+ *   3. The next mount calls `consumeLayout(id)` — if a fresh entry exists
+ *      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.
+ */
+
+/** Parent-relative rect of a measured element (from `onLayout`). */
+export interface SharedRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+interface Entry {
+  rect: SharedRect
+  expiresAt: number
+}
+
+const REGISTRY = new Map<string, Entry>()
+
+/**
+ * How long (ms) a released rect remains consumable. Sized to comfortably
+ * cover a typical screen transition (slide animation, gesture-driven
+ * dismiss) without leaving stale entries lying around if no incoming
+ * mount picks them up.
+ */
+export const SHARED_LAYOUT_TTL_MS = 1000
+
+/**
+ * Provide the current monotonic-ish timestamp. Indirected so tests can
+ * stub it via `__setSharedLayoutClock` without touching `Date.now` globally.
+ */
+let now = (): number => Date.now()
+
+/**
+ * Update the latest known rect for `id`. Called on every `onLayout` of a
+ * 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.
+ */
+export function registerLayout(id: string, rect: SharedRect): void {
+  REGISTRY.set(id, { rect, expiresAt: now() + SHARED_LAYOUT_TTL_MS })
+}
+
+/**
+ * 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.
+ */
+export function releaseLayout(id: string, rect: SharedRect): void {
+  REGISTRY.set(id, { rect, expiresAt: now() + SHARED_LAYOUT_TTL_MS })
+}
+
+/**
+ * Take the recorded rect 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 {
+  const entry = REGISTRY.get(id)
+  if (!entry) return undefined
+  REGISTRY.delete(id)
+  if (entry.expiresAt < now()) return undefined
+  return entry.rect
+}
+
+/** Drop all entries. Tests use this to isolate between cases. */
+export function clearSharedRegistry(): void {
+  REGISTRY.clear()
+}
+
+/**
+ * Inspect a registry entry without consuming it. Intended for tests and
+ * dev tooling; production code should go through `consumeLayout`.
+ */
+export function peekSharedLayout(id: string): SharedRect | undefined {
+  const entry = REGISTRY.get(id)
+  if (!entry) return undefined
+  if (entry.expiresAt < now()) return undefined
+  return entry.rect
+}
+
+/**
+ * Test hook: swap the clock used for TTL calculations. Pass `undefined` to
+ * restore `Date.now`. Not exported from the package root — reachable only
+ * from inside the workspace.
+ */
+export function __setSharedLayoutClock(fn: (() => number) | undefined): void {
+  now = fn ?? Date.now
+}