@rootnative/inertia 0.0.0-alpha.0

package/src/config/MotionConfig.tsx

@@ -0,0 +1,30 @@
+import { type ReactNode, useMemo } from 'react'
+import {
+  MotionConfigContext,
+  type MotionConfigValue,
+  type ReducedMotion,
+} from './MotionConfigContext'
+
+/**
+ * Provider that controls how descendant Motion primitives respond to
+ * reduced-motion preferences. Wrap the root of your app once with the
+ * default (`reducedMotion="user"`) to respect the OS accessibility setting,
+ * or scope a subtree with `'always'` / `'never'` for specific use cases.
+ */
+export function MotionConfig({
+  reducedMotion = 'user',
+  children,
+}: {
+  reducedMotion?: ReducedMotion
+  children: ReactNode
+}) {
+  const value = useMemo<MotionConfigValue>(
+    () => ({ reducedMotion }),
+    [reducedMotion],
+  )
+  return (
+    <MotionConfigContext.Provider value={value}>
+      {children}
+    </MotionConfigContext.Provider>
+  )
+}

package/src/config/MotionConfigContext.ts

@@ -0,0 +1,53 @@
+import { createContext, useContext } from 'react'
+import { useReducedMotion } from 'react-native-reanimated'
+
+/**
+ * How descendant Motion primitives should treat reduced-motion preferences.
+ *
+ * - `'user'` (default): defer to the OS accessibility setting via
+ *   Reanimated's `useReducedMotion()`. This is the only value that respects
+ *   user choice and is the right default for app-level wrappers.
+ * - `'never'`: animate regardless of OS setting. Use sparingly — e.g. for
+ *   onboarding transitions you've decided are essential.
+ * - `'always'`: never animate, regardless of OS setting. Useful for tests
+ *   and snapshots.
+ */
+export type ReducedMotion = 'user' | 'never' | 'always'
+
+export interface MotionConfigValue {
+  reducedMotion: ReducedMotion
+}
+
+/**
+ * Default config used when a Motion primitive is rendered without a
+ * `<MotionConfig>` ancestor. `'user'` means respect the OS setting.
+ */
+export const DEFAULT_MOTION_CONFIG: MotionConfigValue = {
+  reducedMotion: 'user',
+}
+
+export const MotionConfigContext = createContext<MotionConfigValue>(
+  DEFAULT_MOTION_CONFIG,
+)
+
+/**
+ * Read the active `<MotionConfig>` from a descendant. Returns the default
+ * (`'user'`) when no provider is present.
+ */
+export function useMotionConfig(): MotionConfigValue {
+  return useContext(MotionConfigContext)
+}
+
+/**
+ * Resolve the active reduced-motion mode to a boolean. `'user'` consults
+ * Reanimated's OS-backed hook; `'always'` / `'never'` shortcut. Motion
+ * primitives call this to decide whether to swap transitions for
+ * `no-animation`.
+ */
+export function useShouldReduceMotion(): boolean {
+  const { reducedMotion } = useMotionConfig()
+  const osReduced = useReducedMotion()
+  if (reducedMotion === 'never') return false
+  if (reducedMotion === 'always') return true
+  return osReduced
+}

package/src/config/index.ts

@@ -0,0 +1,9 @@
+export { MotionConfig } from './MotionConfig'
+export {
+  MotionConfigContext,
+  DEFAULT_MOTION_CONFIG,
+  useMotionConfig,
+  useShouldReduceMotion,
+  type MotionConfigValue,
+  type ReducedMotion,
+} from './MotionConfigContext'

package/src/gestureLayer/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Opt-in subpath: `@rootnative/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 '@rootnative/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/gestures/focusVisibility.ts

@@ -0,0 +1,61 @@
+import { Platform } from 'react-native'
+
+/**
+ * Input-modality tracker for the `focusVisible` gesture sub-state.
+ *
+ * Implements the W3C `:focus-visible` heuristic: a focus event counts as
+ * "visible" only when the most recent user input was keyboard-driven. Mouse,
+ * pointer, and touch events flip the modality to `'pointer'`; keyboard events
+ * flip it back to `'keyboard'`.
+ *
+ * On native platforms there is no pointer-vs-keyboard distinction — focus
+ * arrives via D-pad, screen reader, or hardware keyboard, all of which are
+ * keyboard-equivalent — so `isFocusVisible()` is unconditionally `true`.
+ *
+ * The web listeners attach lazily on first call (capture phase, so they run
+ * before the focus event reaches the focused element) and stay installed for
+ * the lifetime of the document. They are passive and idle-cheap; the cost is
+ * one boolean read per `onFocus` dispatch.
+ */
+
+type InputModality = 'keyboard' | 'pointer'
+
+// Default to `'keyboard'` so a programmatic / autofocus that happens before
+// any user input still draws a focus ring — matches the W3C polyfill default.
+let modality: InputModality = 'keyboard'
+let installed = false
+
+function setKeyboard() {
+  modality = 'keyboard'
+}
+
+function setPointer() {
+  modality = 'pointer'
+}
+
+function ensureInstalled(): void {
+  if (installed) return
+  if (Platform.OS !== 'web') return
+  if (typeof document === 'undefined') return
+  document.addEventListener('keydown', setKeyboard, true)
+  document.addEventListener('mousedown', setPointer, true)
+  document.addEventListener('pointerdown', setPointer, true)
+  document.addEventListener('touchstart', setPointer, true)
+  installed = true
+}
+
+/**
+ * `true` if the next `onFocus` should be treated as "focus-visible" (keyboard
+ * focus). On native, always `true`. On web, reflects the most recent user
+ * input modality.
+ */
+export function isFocusVisible(): boolean {
+  if (Platform.OS !== 'web') return true
+  ensureInstalled()
+  return modality === 'keyboard'
+}
+
+/** @internal — test-only hook to reset module state between cases. */
+export function __resetFocusVisibilityForTests(next: InputModality): void {
+  modality = next
+}

package/src/gestures/index.ts

@@ -0,0 +1 @@
+export { isFocusVisible } from './focusVisibility'

package/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * `@rootnative/inertia` — declarative animation primitives for React Native.
+ *
+ * v0.1 surface: `Motion.View` / `Motion.Text` / `Motion.Image` /
+ * `Motion.Pressable` / `Motion.ScrollView`, with `initial` / `animate` /
+ * `exit` / `transition` / `variants` / `gesture` / `controller` /
+ * `onAnimationEnd` props. Sequences, repeats (single-value and
+ * sequence-level), spring / timing / decay / no-animation transitions,
+ * and `<Presence>` for mount / unmount transitions all in scope.
+ * `<MotionConfig reducedMotion>` gates motion against the OS setting.
+ */
+export {
+  Motion,
+  MotionView,
+  MotionText,
+  MotionImage,
+  MotionPressable,
+  MotionScrollView,
+  createMotionComponent,
+} from './motion'
+export { MotionConfig, useMotionConfig, useShouldReduceMotion } from './config'
+export type { MotionConfigValue, ReducedMotion } from './config'
+export { Presence, usePresence } from './presence'
+export type { PresenceContextValue } from './presence'
+export {
+  buildReleaseAnimation,
+  resolveTransition,
+  resolveAnimatableValue,
+  ensureWorkletEasing,
+} 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 {
+  AnimatableValue,
+  AnimateStyle,
+  AnimationCallbackInfo,
+  DecayTransition,
+  GestureSubStates,
+  MotionComponent,
+  MotionProps,
+  NoAnimationTransition,
+  PerPropertyTransition,
+  RepeatConfig,
+  SequenceStep,
+  SpringTransition,
+  TimingTransition,
+  Transition,
+  TransitionConfig,
+  VariantController,
+  VariantsMap,
+} from './types'

package/src/layout/index.ts

@@ -0,0 +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/resolveLayout.ts

@@ -0,0 +1,54 @@
+import { LinearTransition } from 'react-native-reanimated'
+import { ensureWorkletEasing } from '../transitions/easing'
+import { DEFAULT_SPRING, springToReanimated } from '../transitions/spring'
+import { type TransitionConfig } from '../types'
+
+export type LayoutProp = boolean | TransitionConfig | undefined
+
+/**
+ * Resolve the public `layout` prop into a Reanimated `LinearTransition` builder.
+ *
+ * - `undefined` / `false` / `{ type: 'no-animation' }` → `undefined` (no layout
+ *   animation; layout changes snap).
+ * - `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: 'decay', ... }` → silently downgrades to spring; decay doesn't
+ *   have a clear target for a layout transition.
+ *
+ * When `reducedMotion` is true the caller should pass `undefined` so the
+ * underlying component renders without a layout animation at all. We choose
+ * this over `LinearTransition.duration(0)` because Reanimated still runs the
+ * commit-tracking machinery in that case; the snap path is genuinely cheaper.
+ */
+export function resolveLayoutTransition(
+  layout: LayoutProp,
+): LinearTransition | undefined {
+  if (!layout) return undefined
+
+  const cfg: TransitionConfig = layout === true ? { type: 'spring' } : layout
+
+  if (cfg.type === 'no-animation') return undefined
+
+  if (cfg.type === 'timing') {
+    let builder = LinearTransition.duration(cfg.duration ?? 300)
+    const easing = ensureWorkletEasing(cfg.easing)
+    if (easing) builder = builder.easing(easing)
+    if (cfg.delay) builder = builder.delay(cfg.delay)
+    return builder
+  }
+
+  const spring = cfg.type === 'decay' ? ({ type: 'spring' } as const) : cfg
+  const { stiffness, damping, mass } = springToReanimated({
+    ...DEFAULT_SPRING,
+    ...spring,
+  })
+  let builder = LinearTransition.springify()
+    .stiffness(stiffness)
+    .damping(damping)
+    .mass(mass)
+  if ('delay' in spring && spring.delay) builder = builder.delay(spring.delay)
+  return builder
+}