@onlynative/inertia 0.0.1-alpha.0 → 0.0.1-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlynative/inertia",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.1",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "OnlyNative",
@@ -72,6 +72,13 @@
       "import": "./dist/motion/ScrollView.mjs",
       "require": "./dist/motion/ScrollView.js"
     },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "react-native": "./src/testing/index.ts",
+      "source": "./src/testing/index.ts",
+      "import": "./dist/testing/index.mjs",
+      "require": "./dist/testing/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -84,16 +91,6 @@
     "!**/__tests__",
     "!**/*.test.*"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "jest",
-    "size": "size-limit",
-    "size:why": "size-limit --why",
-    "lint": "eslint src",
-    "clean": "rm -rf dist .turbo *.tsbuildinfo"
-  },
   "peerDependencies": {
     "react": ">=19.0.0",
     "react-native": ">=0.81.0",
@@ -116,5 +113,15 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "size": "size-limit",
+    "size:why": "size-limit --why",
+    "lint": "eslint src",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
   }
-}
+}

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/motion/createMotionComponent.tsx

@@ -13,6 +13,7 @@ import Animated, {
   type SharedValue,
 } from 'react-native-reanimated'
 import { useShouldReduceMotion } from '../config'
+import { isFocusVisible } from '../gestures'
 import { usePresence } from '../presence'
 import { resolveAnimatableValue } from '../transitions'
 import {
@@ -187,10 +188,11 @@ export function createMotionComponent<C extends ComponentType<any>>(
 
     // Gesture sub-state activation tracked as JS state so changes invalidate
     // the merged-target signature and re-run the animation effect. The cost
-    // is three useState slots regardless of whether `gesture` is set; that's
+    // is four useState slots regardless of whether `gesture` is set; that's
     // tiny and lets us stay rules-of-hooks-clean.
     const [pressed, setPressed] = useState(false)
     const [focused, setFocused] = useState(false)
+    const [focusVisible, setFocusVisible] = useState(false)
     const [hovered, setHovered] = useState(false)
 
     // The set of keys this instance animates is locked at first render. With
@@ -217,6 +219,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
         for (const subState of [
           gesture.pressed,
           gesture.focused,
+          gesture.focusVisible,
           gesture.hovered,
         ] as Array<object | undefined>) {
           if (!subState) continue
@@ -261,6 +264,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
         : mergeGestureTargets(animateRecord, gesture, {
             pressed,
             focused,
+            focusVisible,
             hovered,
           })
     const mergedSig =
@@ -383,6 +387,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
       rest as Record<string, unknown>,
       setPressed,
       setFocused,
+      setFocusVisible,
       setHovered,
     )
 
@@ -719,12 +724,18 @@ function stableStringify(v: unknown): string {
  * by any declared sub-state are always present in the result so releasing a
  * gesture animates the property back to a defined value (the base `animate`
  * value when present, otherwise `DEFAULT_RESTING`). Sub-states layer in
- * priority order: `hovered` < `focused` < `pressed`.
+ * priority order (lowest first):
+ * `hovered` < `focused` < `focusVisible` < `pressed`.
  */
 function mergeGestureTargets(
   base: Partial<Record<AnimatableKey, AnimatableValue<number>>>,
   gesture: GestureSubStates<unknown> | undefined,
-  active: { pressed: boolean; focused: boolean; hovered: boolean },
+  active: {
+    pressed: boolean
+    focused: boolean
+    focusVisible: boolean
+    hovered: boolean
+  },
 ): Partial<Record<AnimatableKey, AnimatableValue<number>>> {
   if (!gesture) return base
   const merged: Partial<Record<AnimatableKey, AnimatableValue<number>>> = {
@@ -733,6 +744,7 @@ function mergeGestureTargets(
   const subStates = [
     gesture.hovered,
     gesture.focused,
+    gesture.focusVisible,
     gesture.pressed,
   ] as Array<
     Partial<Record<AnimatableKey, AnimatableValue<number>>> | undefined
@@ -761,6 +773,14 @@ function mergeGestureTargets(
       >,
     )
   }
+  if (active.focusVisible && gesture.focusVisible) {
+    Object.assign(
+      merged,
+      gesture.focusVisible as Partial<
+        Record<AnimatableKey, AnimatableValue<number>>
+      >,
+    )
+  }
   if (active.pressed && gesture.pressed) {
     Object.assign(
       merged,
@@ -788,6 +808,7 @@ function useGestureHandlers(
   rest: Record<string, unknown>,
   setPressed: (next: boolean) => void,
   setFocused: (next: boolean) => void,
+  setFocusVisible: (next: boolean) => void,
   setHovered: (next: boolean) => void,
 ): GestureHandlers {
   return useMemo(() => {
@@ -804,9 +825,20 @@ function useGestureHandlers(
       handlers.onPressIn = compose(rest.onPressIn, () => setPressed(true))
       handlers.onPressOut = compose(rest.onPressOut, () => setPressed(false))
     }
-    if (gesture.focused) {
-      handlers.onFocus = compose(rest.onFocus, () => setFocused(true))
-      handlers.onBlur = compose(rest.onBlur, () => setFocused(false))
+    // Mount onFocus/onBlur if either focus sub-state is declared. The two flags
+    // are independent: `focused` always tracks focus; `focusVisible` only
+    // engages when the most recent input was keyboard (W3C `:focus-visible`
+    // semantics). On native the modality is always `'keyboard'`, so the two
+    // flags move together.
+    if (gesture.focused || gesture.focusVisible) {
+      handlers.onFocus = compose(rest.onFocus, () => {
+        if (gesture.focused) setFocused(true)
+        if (gesture.focusVisible && isFocusVisible()) setFocusVisible(true)
+      })
+      handlers.onBlur = compose(rest.onBlur, () => {
+        if (gesture.focused) setFocused(false)
+        if (gesture.focusVisible) setFocusVisible(false)
+      })
     }
     if (gesture.hovered) {
       // Web-only events. RN-Web 0.72+ accepts these on View; native ignores
@@ -821,6 +853,7 @@ function useGestureHandlers(
   }, [
     gesture?.pressed ? 1 : 0,
     gesture?.focused ? 1 : 0,
+    gesture?.focusVisible ? 1 : 0,
     gesture?.hovered ? 1 : 0,
     rest.onTouchStart,
     rest.onTouchEnd,

package/src/testing/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Test helpers for Inertia consumers.
+ *
+ * The Reanimated Jest mock that ships with the library is **static-render**:
+ * `useAnimatedStyle` runs the worklet exactly once per call, and shared
+ * values are plain `{ value }` refs. After the animation effect fires
+ * (`sv.value = withSpring(target) → target` under the mock), the rendered
+ * style has already been captured at the at-rest shared-value snapshot —
+ * so without intervention, every Inertia component looks frozen at its
+ * `initial` values in tests.
+ *
+ * `renderWithMotion` papers over that by forcing a second render after the
+ * first effect pass. The shared values now hold their target values, so
+ * `useAnimatedStyle` re-evaluates against the post-animation state and the
+ * rendered styles match what a real device would settle on.
+ *
+ * Use this from `@onlynative/inertia/testing`:
+ *
+ * ```ts
+ * import { renderWithMotion } from '@onlynative/inertia/testing'
+ *
+ * const { getByTestId } = renderWithMotion(
+ *   <Motion.View testID="card" initial={{ opacity: 0 }} animate={{ opacity: 1 }} />,
+ * )
+ * // getByTestId('card') has opacity: 1, not 0.
+ * ```
+ *
+ * For tests that need to re-render with new props and re-flush, use
+ * `flushMotion(result, nextUi)`.
+ */
+import { render, type RenderOptions } from '@testing-library/react-native'
+import { cloneElement, type ReactElement } from 'react'
+
+type RenderResult = ReturnType<typeof render>
+
+/**
+ * Render a Motion subtree and immediately flush animations to their target
+ * values. Returns the standard `@testing-library/react-native` render result.
+ *
+ * Internally this calls `render(...)`, then re-renders the same element
+ * inside `act(...)` so the post-effect shared-value updates flow into the
+ * `useAnimatedStyle` re-run. Both passes happen synchronously — the call
+ * returns once styles reflect the `animate` target.
+ */
+export function renderWithMotion(
+  ui: ReactElement,
+  options?: RenderOptions,
+): RenderResult {
+  const result = render(ui, options)
+  // `cloneElement` produces a fresh element with the same props so React
+  // doesn't bail out of the second render via reference-equal short-circuit
+  // — that's what causes `useAnimatedStyle` to skip its post-effect re-read
+  // when the same element is passed to `rerender`.
+  flushMotion(result, cloneElement(ui))
+  return result
+}
+
+/**
+ * Re-render a previously-mounted Motion subtree to flush pending animations
+ * to their target values. Pass the same element you originally rendered
+ * (or a new one for tests that update props between flushes).
+ *
+ * The flush is synchronous. `@testing-library/react-native`'s `rerender`
+ * already wraps in `act` internally, so no explicit `act(...)` is needed
+ * here.
+ */
+export function flushMotion(rendered: RenderResult, ui: ReactElement): void {
+  // One re-render is enough for non-sequence animations: the mount-effect
+  // has run, shared values now hold their target values, and the next
+  // `useAnimatedStyle` invocation will read them. Sequence steps chain
+  // through `withSpring` / `withTiming` settle callbacks — those are still
+  // captured for tests that invoke them manually (see `onAnimationEnd.test`).
+  //
+  // `cloneElement` defeats React's reference-equal element bail-out so the
+  // second render actually reaches `useAnimatedStyle` instead of being
+  // short-circuited by the reconciler.
+  rendered.rerender(cloneElement(ui))
+}

package/src/types.ts

@@ -113,17 +113,34 @@ export type VariantsMap<C> = Record<string, AnimateStyle<C>>
  *
  * - `pressed` — active while the user is touching the component (touch start
  *   to touch end / cancel).
- * - `focused` — active while a focusable component owns keyboard focus
- *   (no-op for non-focusable underlying components).
+ * - `focused` — active while a focusable component owns focus, regardless of
+ *   how focus arrived (mouse, touch, or keyboard). No-op for non-focusable
+ *   underlying components.
+ * - `focusVisible` — active only when focus arrived from the keyboard
+ *   (W3C `:focus-visible` semantics). Use this for focus rings to avoid
+ *   flashing them on click-focus on web. On native — where focus always
+ *   arrives via D-pad, screen reader, or hardware keyboard — this behaves
+ *   identically to `focused`.
  * - `hovered` — web-only. Typed for cross-platform call sites; the runtime is
  *   a no-op on native.
  *
  * When a sub-state is active, its values override the base `animate` target
- * per-property. Priority on overlap: `pressed` > `focused` > `hovered`.
+ * per-property. Priority on overlap (highest first):
+ * `pressed` > `focusVisible` > `focused` > `hovered`. `focusVisible` layers
+ * above `focused` so declaring both yields a state-layer on any focus and a
+ * ring on keyboard focus only.
+ *
+ * Sub-states stack as **single-state selection**, not blended interpolation:
+ * the highest-priority active key's value wins per-property, with one
+ * transition between target values. Mid-transition cross-fades between
+ * sub-states (e.g. release-while-still-hovered) follow the standard `transition`
+ * for that property — the resolver does not run multiple parallel
+ * interpolations the way a hand-rolled chained-`interpolateColor` would.
  */
 export interface GestureSubStates<C> {
   pressed?: AnimateStyle<C>
   focused?: AnimateStyle<C>
+  focusVisible?: AnimateStyle<C>
   hovered?: AnimateStyle<C>
 }