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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlynative/inertia",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.2",
   "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 {
@@ -43,7 +44,28 @@ const TRANSFORM_KEYS = [
   'rotate',
 ] as const
 
-const TOP_LEVEL_KEYS = ['opacity', 'width', 'height', 'borderRadius'] as const
+const NUMERIC_TOP_LEVEL_KEYS = [
+  'opacity',
+  'width',
+  'height',
+  'borderRadius',
+] as const
+
+// Color-valued keys. Reanimated's value setter detects color strings and
+// interpolates between their packed RGBA representations natively in
+// `withSpring` / `withTiming` — so the resolver path is identical to numeric
+// keys; only the shared-value seed and the resting default differ.
+//
+// `tintColor` is Image-only, but allocated unconditionally here: the
+// per-primitive type system (`AnimateStyle<C>`) is what gates which keys
+// `animate` accepts at compile time. An unused shared value is a single ref;
+// allocating it everywhere keeps hook order stable and the factory generic.
+const COLOR_KEYS = [
+  'backgroundColor',
+  'borderColor',
+  'color',
+  'tintColor',
+] as const
 
 /**
  * Per-effect transform-group coordinator. Counts how many transform-axis
@@ -53,7 +75,11 @@ const TOP_LEVEL_KEYS = ['opacity', 'width', 'height', 'borderRadius'] as const
  */
 type TransformGroup = { remaining: number }
 
-const ALL_KEYS = [...TRANSFORM_KEYS, ...TOP_LEVEL_KEYS] as const
+const ALL_KEYS = [
+  ...TRANSFORM_KEYS,
+  ...NUMERIC_TOP_LEVEL_KEYS,
+  ...COLOR_KEYS,
+] as const
 type AnimatableKey = (typeof ALL_KEYS)[number]
 type TransformKey = (typeof TRANSFORM_KEYS)[number]
 
@@ -64,7 +90,7 @@ const TRANSFORM_KEY_SET = new Set<AnimatableKey>(TRANSFORM_KEYS)
 // Reanimated's style merging treats it as a no-op when present.
 const EXITING_POINTER_EVENTS_STYLE = { pointerEvents: 'none' } as const
 
-const DEFAULT_RESTING: Record<AnimatableKey, number> = {
+const DEFAULT_RESTING: Record<AnimatableKey, number | string> = {
   translateX: 0,
   translateY: 0,
   scale: 1,
@@ -75,6 +101,14 @@ const DEFAULT_RESTING: Record<AnimatableKey, number> = {
   width: 0,
   height: 0,
   borderRadius: 0,
+  // 'transparent' is the only safe universal default for colors: it works as
+  // an initial seed for any color animation (no jarring opaque flash on mount
+  // when `initial` is omitted) and rgba(0,0,0,0) interpolates cleanly into
+  // any opaque target via Reanimated's color util.
+  backgroundColor: 'transparent',
+  borderColor: 'transparent',
+  color: 'transparent',
+  tintColor: 'transparent',
 }
 
 const TRANSITION_KEYS = new Set([
@@ -116,10 +150,9 @@ function transitionFor<S>(
  * `exit` / `transition` all infer from `C`'s `style` prop. There is no
  * shared `ViewStyle & TextStyle & ImageStyle` fallback.
  *
- * Alpha scope: numeric properties listed in `ALL_KEYS`, applied via
- * Reanimated shared values + `useAnimatedStyle`. Sequences, variants,
- * gestures, color animation, and the cross-render memoization optimization
- * land in later phases.
+ * Alpha scope: numeric properties (transforms, opacity, width, height,
+ * borderRadius) and color properties (backgroundColor, borderColor, color,
+ * tintColor) applied via Reanimated shared values + `useAnimatedStyle`.
  */
 export function createMotionComponent<C extends ComponentType<any>>(
   Component: C,
@@ -175,22 +208,25 @@ export function createMotionComponent<C extends ComponentType<any>>(
     )
 
     const animateRecord = (resolvedAnimate ?? {}) as Partial<
-      Record<AnimatableKey, AnimatableValue<number>>
+      Record<AnimatableKey, AnimatableValue<number | string>>
     >
     const initialRecord =
       initial && initial !== false
-        ? (initial as Partial<Record<AnimatableKey, number>>)
+        ? (initial as Partial<Record<AnimatableKey, number | string>>)
         : undefined
     const exitRecord = exit
-      ? (exit as Partial<Record<AnimatableKey, AnimatableValue<number>>>)
+      ? (exit as Partial<
+          Record<AnimatableKey, AnimatableValue<number | string>>
+        >)
       : undefined
 
     // 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 +253,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 +298,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
         : mergeGestureTargets(animateRecord, gesture, {
             pressed,
             focused,
+            focusVisible,
             hovered,
           })
     const mergedSig =
@@ -383,6 +421,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
       rest as Record<string, unknown>,
       setPressed,
       setFocused,
+      setFocusVisible,
       setHovered,
     )
 
@@ -401,7 +440,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
   return Motion as unknown as MotionComponent<C>
 }
 
-type SharedValueMap = Record<AnimatableKey, SharedValue<number>>
+type SharedValueMap = Record<AnimatableKey, SharedValue<number | string>>
 
 /**
  * Allocate one shared value per animatable key in `ALL_KEYS` and return a
@@ -417,21 +456,29 @@ type SharedValueMap = Record<AnimatableKey, SharedValue<number>>
  *
  * Hooks are called in a stable, lexical order — fine for rules-of-hooks.
  * Unused shared values are cheap; the worklet skips them via
- * `activeKeysRef`.
+ * `activeKeysRef`. Color keys are seeded with the initial color string so
+ * Reanimated's value setter recognizes the slot as a color from the first
+ * `withSpring` / `withTiming` call.
  */
 function useAnimatableSharedValues(
-  init: (key: AnimatableKey) => number,
+  init: (key: AnimatableKey) => number | string,
 ): SharedValueMap {
-  const translateX = useSharedValue(init('translateX'))
-  const translateY = useSharedValue(init('translateY'))
-  const scale = useSharedValue(init('scale'))
-  const scaleX = useSharedValue(init('scaleX'))
-  const scaleY = useSharedValue(init('scaleY'))
-  const rotate = useSharedValue(init('rotate'))
-  const opacity = useSharedValue(init('opacity'))
-  const width = useSharedValue(init('width'))
-  const height = useSharedValue(init('height'))
-  const borderRadius = useSharedValue(init('borderRadius'))
+  const translateX = useSharedValue<number | string>(init('translateX'))
+  const translateY = useSharedValue<number | string>(init('translateY'))
+  const scale = useSharedValue<number | string>(init('scale'))
+  const scaleX = useSharedValue<number | string>(init('scaleX'))
+  const scaleY = useSharedValue<number | string>(init('scaleY'))
+  const rotate = useSharedValue<number | string>(init('rotate'))
+  const opacity = useSharedValue<number | string>(init('opacity'))
+  const width = useSharedValue<number | string>(init('width'))
+  const height = useSharedValue<number | string>(init('height'))
+  const borderRadius = useSharedValue<number | string>(init('borderRadius'))
+  const backgroundColor = useSharedValue<number | string>(
+    init('backgroundColor'),
+  )
+  const borderColor = useSharedValue<number | string>(init('borderColor'))
+  const color = useSharedValue<number | string>(init('color'))
+  const tintColor = useSharedValue<number | string>(init('tintColor'))
 
   const ref = useRef<SharedValueMap | null>(null)
   if (ref.current === null) {
@@ -446,6 +493,10 @@ function useAnimatableSharedValues(
       width,
       height,
       borderRadius,
+      backgroundColor,
+      borderColor,
+      color,
+      tintColor,
     }
   }
   return ref.current
@@ -467,7 +518,7 @@ function useAnimatableSharedValues(
  */
 function makeKeyCallbackFactory(
   key: string,
-  sharedValue: SharedValue<number>,
+  sharedValue: SharedValue<number | string>,
   target: number | string | undefined,
   onAnimationEndRef: {
     current: ((info: AnimationCallbackInfo<unknown>) => void) | undefined
@@ -572,7 +623,7 @@ function makeKeyCallbackFactory(
  * Number of sequence steps in an animatable value. `1` for plain values and
  * single-step `{ to }` objects; the array length for keyframe arrays.
  */
-function stepCountOf(v: AnimatableValue<number> | undefined): number {
+function stepCountOf(v: AnimatableValue<number | string> | undefined): number {
   if (Array.isArray(v)) return v.length
   return 1
 }
@@ -600,13 +651,13 @@ function totalIterationsOf(cfg: TransitionConfig | undefined): number {
  * objects use `to`. Returns `undefined` for unrecognized shapes.
  */
 function targetEndValue(
-  v: AnimatableValue<number> | undefined,
+  v: AnimatableValue<number | string> | undefined,
 ): number | string | undefined {
   if (v === undefined) return undefined
   if (typeof v === 'number' || typeof v === 'string') return v
   if (Array.isArray(v)) {
     return v.length > 0
-      ? targetEndValue(v[v.length - 1] as AnimatableValue<number>)
+      ? targetEndValue(v[v.length - 1] as AnimatableValue<number | string>)
       : undefined
   }
   if (typeof v === 'object' && v !== null && 'to' in v) {
@@ -662,20 +713,24 @@ function resolveAnimateInput(
 declare const __DEV__: boolean
 
 /**
- * Pick the resting/initial-frame number out of an `AnimatableValue`. Plain
- * numbers come through unchanged; sequence arrays use their first element;
- * `{ to }` step objects use `to`. Non-numeric or unresolvable shapes return
+ * Pick the resting/initial-frame value out of an `AnimatableValue`. Plain
+ * numbers and color strings come through unchanged; sequence arrays use their
+ * first element; `{ to }` step objects use `to`. Unresolvable shapes return
  * `undefined` so the caller can fall back to `DEFAULT_RESTING`.
  */
-function restValue(v: AnimatableValue<number> | undefined): number | undefined {
+function restValue(
+  v: AnimatableValue<number | string> | undefined,
+): number | string | undefined {
   if (v === undefined) return undefined
-  if (typeof v === 'number') return v
+  if (typeof v === 'number' || typeof v === 'string') return v
   if (Array.isArray(v)) {
-    return v.length > 0 ? restValue(v[0] as AnimatableValue<number>) : undefined
+    return v.length > 0
+      ? restValue(v[0] as AnimatableValue<number | string>)
+      : undefined
   }
   if (typeof v === 'object' && v !== null && 'to' in v) {
     const to = (v as { to: unknown }).to
-    return typeof to === 'number' ? to : undefined
+    return typeof to === 'number' || typeof to === 'string' ? to : undefined
   }
   return undefined
 }
@@ -719,23 +774,32 @@ 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>>>,
+  base: Partial<Record<AnimatableKey, AnimatableValue<number | string>>>,
   gesture: GestureSubStates<unknown> | undefined,
-  active: { pressed: boolean; focused: boolean; hovered: boolean },
-): Partial<Record<AnimatableKey, AnimatableValue<number>>> {
+  active: {
+    pressed: boolean
+    focused: boolean
+    focusVisible: boolean
+    hovered: boolean
+  },
+): Partial<Record<AnimatableKey, AnimatableValue<number | string>>> {
   if (!gesture) return base
-  const merged: Partial<Record<AnimatableKey, AnimatableValue<number>>> = {
+  const merged: Partial<
+    Record<AnimatableKey, AnimatableValue<number | string>>
+  > = {
     ...base,
   }
   const subStates = [
     gesture.hovered,
     gesture.focused,
+    gesture.focusVisible,
     gesture.pressed,
   ] as Array<
-    Partial<Record<AnimatableKey, AnimatableValue<number>>> | undefined
+    Partial<Record<AnimatableKey, AnimatableValue<number | string>>> | undefined
   >
   for (const sub of subStates) {
     if (!sub) continue
@@ -749,7 +813,7 @@ function mergeGestureTargets(
     Object.assign(
       merged,
       gesture.hovered as Partial<
-        Record<AnimatableKey, AnimatableValue<number>>
+        Record<AnimatableKey, AnimatableValue<number | string>>
       >,
     )
   }
@@ -757,7 +821,15 @@ function mergeGestureTargets(
     Object.assign(
       merged,
       gesture.focused as Partial<
-        Record<AnimatableKey, AnimatableValue<number>>
+        Record<AnimatableKey, AnimatableValue<number | string>>
+      >,
+    )
+  }
+  if (active.focusVisible && gesture.focusVisible) {
+    Object.assign(
+      merged,
+      gesture.focusVisible as Partial<
+        Record<AnimatableKey, AnimatableValue<number | string>>
       >,
     )
   }
@@ -765,7 +837,7 @@ function mergeGestureTargets(
     Object.assign(
       merged,
       gesture.pressed as Partial<
-        Record<AnimatableKey, AnimatableValue<number>>
+        Record<AnimatableKey, AnimatableValue<number | string>>
       >,
     )
   }
@@ -788,6 +860,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 +877,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 +905,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>
 }