Fix MotionStyle type conflict with React 19 CSSProperties

[mattgperry]

Exclude x, y, z from CSSProperties when creating MotionCSS type to prevent TypeScript error "Interface 'MotionStyle' cannot simultaneously extend types" when using Motion with React 19 and skipLibCheck: false.

React 19's CSSProperties now includes x, y, z properties which conflict with Motion's TransformProperties. This follows the same pattern already used in CSSStyleDeclarationWithTransform.

Fixes #3422

[claude]

PR Review: Fix MotionStyle type conflict with React 19 CSSProperties

Summary

This PR addresses a TypeScript compilation error (TS2320) that occurs when using Motion with React 19 and skipLibCheck: false. The fix excludes x, y, and z properties from React's CSSProperties when creating the MotionCSS type, preventing a conflict with Motion's TransformProperties.

Code Quality ✅

Positive:

• The fix follows the existing pattern already established in CSSStyleDeclarationWithTransform (packages/motion-dom/src/animation/types.ts:551), which also excludes x, y, z from the base CSS type
• Minimal, surgical change that only modifies what's necessary
• Consistent with the codebase's approach to handling transform property conflicts
• The solution directly addresses the root cause: React 19 added x, y, z to its CSSProperties interface, creating a collision with Motion's TransformProperties interface

Code location: packages/framer-motion/src/motion/types.ts:34

Type Safety ✅

The fix is type-safe and correct:

• MotionStyle extends both MotionCSS and MotionTransform (lines 60-63)
• MotionTransform wraps TransformProperties which defines x, y, z (motion-dom/src/animation/types.ts:608-611)
• By excluding these properties from MotionCSS, we avoid the "cannot simultaneously extend" error while preserving Motion's transform property definitions
• The properties are still available on MotionStyle through MotionTransform

Potential Issues ⚠️

Minor consideration:

• No type-level tests exist for MotionStyle or MotionCSS (verified via grep)
• Consider adding a TypeScript compilation test to prevent future regressions, especially for React version compatibility

Suggestion: Create a type-level test file like:

// packages/framer-motion/src/motion/__tests__/types.test-d.ts
import { expectType } from 'tsd'
import { MotionStyle } from '../types'

// Ensure x, y, z are available and accept both numbers and MotionValues
const style: MotionStyle = {
  x: 100,
  y: 100,
  z: 100,
}

Performance Considerations ✅

No performance impact - this is a pure type-level change with zero runtime implications.

Security Concerns ✅

No security concerns - type definitions don't affect runtime behavior.

Test Coverage ⚠️

Observation:

• The fix resolves the compilation error described in issue [BUG] Interface 'MotionStyle' cannot simultaneously extend types #3422
• No new runtime tests needed (type-only change)
• However, the PR doesn't include a TypeScript compilation test case to prevent regression

Recommendation:

• Add the reproduction case from [BUG] Interface 'MotionStyle' cannot simultaneously extend types #3422 to the React 19 dev app (dev/react-19) to ensure this scenario continues to compile
• Alternatively, add a type-level test using tsd or similar

Compatibility ✅

• React 18: No impact (React 18's CSSProperties doesn't include x, y, z)
• React 19: Fixes the compilation error
• Backward compatible: The change only affects type checking, not runtime behavior

Conclusion

LGTM with minor suggestion ✅

This is a well-targeted fix that correctly resolves the React 19 type conflict. The solution:

• ✅ Follows existing patterns in the codebase
• ✅ Minimal and focused change
• ✅ Type-safe and backward compatible
• ✅ Directly addresses the root cause

Optional enhancement: Consider adding a TypeScript compilation test to catch similar issues in future React updates.

Approval Status: Ready to merge ✅