RFC: Reject unknown top-level props in spring hooks

Summary

The public types for the spring hooks silently accept properties that aren't part of the API. This is the root cause of #2198 (and likely an unknown number of other "useChain doesn't work" / "delay isn't applied" reports): users write useSpring({ squareRef, ... }) instead of useSpring({ ref: squareRef, ... }) and get no compile-time signal. The spring then auto-starts (no ref ⇒ no imperative gating), which looks like a runtime bug but is a silently-dropped prop.

This RFC proposes tightening the prop types to flag unknown keys at the top level while preserving arbitrary animatable values inside from / to / update / etc.

Motivation

A minimal repro that compiles clean today:

const ref = useSpringRef()
useSpring({
  squareRef: ref,       // ← typo, no error
  randomKey: 'hello',   // ← also no error
  from: { x: 0 },
  to: { x: 100 },
})

Why this slips through: useSpring's signature is

useSpring<Props extends object>(
  props: (Props & Valid<Props, UseSpringProps<Props>>) | UseSpringProps
): SpringValues<PickAnimated<Props>>

Props is inferred from the call site, so any extra key becomes part of Props itself. Valid<T, U> (in types/common.ts) intersects keyof T & keyof U and only flags keys whose types disagree — it has no concept of "keys in T that aren't in U".

The result: typos in control props (ref, config, delay, immediate, loop, reset, reverse, onStart, onRest, …) and in shorthand fields silently no-op.

Detailed design

Split the prop surface into two distinct shapes:

type ControlProps<State> = {
  ref?: SpringRef<State>
  config?: SpringConfig | ((key: keyof State) => SpringConfig)
  delay?: number | ((key: keyof State) => number)
  immediate?: boolean | ((key: keyof State) => boolean)
  loop?: LoopProp<State>
  pause?: boolean
  cancel?: boolean | string | string[] | ((key: keyof State) => boolean)
  reset?: boolean | ((key: keyof State) => boolean)
  reverse?: boolean
  default?: boolean | Partial<ControlProps<State>>
  // ...lifecycle: onStart, onChange, onRest, onPause, onResume, onResolve
  // ...sources: from, to, update
}

type AnimatableValues<State extends Lookup> = State // open shape; the values.

type UseSpringProps<State extends Lookup = Lookup> = ControlProps<State> & {
  from?: Partial<AnimatableValues<State>>
  to?: GoalValues<State>  // single | array | async fn — current shape
  update?: Partial<AnimatableValues<State>>
}

Then the public hook signature becomes a strict object type (no Props extends object inference seam at the top level):

function useSpring<State extends Lookup>(
  props: UseSpringProps<State>
): SpringValues<State>

with the conventional overloads for the deps / function-props variants.

Excess-property checking now applies because the object literal is checked directly against a fixed type, not against an inferred mirror of itself. Animation values live inside from / to / update, where the open shape is needed and harmless.

What this catches

• { squareRef: ref, ... } → error ("squareRef does not exist on UseSpringProps")
• { confg: { duration: 200 } } (typo) → error
• { onRset: ... } → error
• { to: { x: 100 }, x: 100 } (animation value at top level instead of in to) → error

What this preserves

• useSpring({ from: { wibble: 0 }, to: { wibble: 100 } }) — still fine, wibble is inside from/to.
• The function form useSpring((i, ctrl) => ({ ... })).
• The deps array.

Drawbacks

1. Breaking type-only change. Code that today smuggles arbitrary keys at the top level (e.g. relying on from-less shorthand useSpring({ x: 0 }) to set the goal) will now error.

   Mitigation: this pattern is already discouraged in the docs — from / to are the canonical entry points. Provide a codemod for the obvious shape ({ x: 0, y: 0 } → { to: { x: 0, y: 0 } }).

2. useTransition items. Transitions accept { from, enter, leave, update, ... } plus arbitrary control props. Same split applies but the surface is bigger; needs auditing per-hook.

3. Pre-existing Valid<> machinery. Still useful for the inferred-state cases (function-props, where State comes from the return type). Keep it for that path.

Alternatives

• Status quo + lint rule. Ship an ESLint rule that flags unknown keys in spring hook call sites. Lower ergonomic cost but doesn't help users without ESLint or with non-literal call sites.

• Runtime warn in dev. Add a process.env.NODE_ENV !== 'production' check that warns on unknown keys at the controller layer. Cheap to ship, catches it eventually, but the failure mode is still "your animation silently doesn't sequence" rather than a red squiggle.

• Brand the ref prop. Make ref a required prop in a sub-type guarded by a brand to force users to spell it. Too invasive, breaks ergonomic shorthand for non-chained uses.

Open questions

1. Is the function-props overload (useSpring((i, ctrl) => props)) reachable from this tightening without regression? The return type of the function would still need the same strict shape.

2. Codemod scope — community packages and example snippets all over the place. How aggressive should the migration tooling be?

3. Should the same treatment extend to Controller.start(props) and SpringValue.start(props) for symmetry?

Start by reading types/common.ts and the current useSpring type signature, then trace the deps and function-props overloads plus the related useTransition surface. Done means unknown top-level control keys are rejected while arbitrary animation values remain valid inside from, to, and update, with existing overload behavior preserved.