feat: eliminate one frame delay in `onMove` handler on iOS

kirillzyusko commented 5 months ago

📜 Description

Improved precision of onMove handler to drive animation frame-in-frame using this handler.

💡 Motivation and Context

This problem was introduced since https://github.com/kirillzyusko/react-native-keyboard-controller/pull/87 was merged.

The thing is that we are reading layer properties using CADisplayLink. The problem is that in this case we read always out-of-date values, because CADisplayLink fires a callback before the next frame - in this case we'll always read a value for a previous frame. Thus we have always one frame delay.

The idea of this PR is to have an ability to read future values and use them. For that I had to replicate how SpringAnimation calculates its values (i. e. the math behind it, because default CASpringAnimation class doesn't give us such ability).

Now we know all variables - current timestamp, beginning of the animation, next scheduled timestamp etc. so we can calculate the next frame.

However it's also tricky, because in my observation:

the algorithm how next frame will be rendered is different if we compare simulator vs actual device (on a real device we have a bigger delay);
if debugger from XCode is attached, then frames are also calculated slightly different.

So the formula like targetTimestamp - beginTime + duration may work good if XCode debugger is not attached, but will produce junky animation when debugger is attached.

I struggled a lot and found that CADisplayLink can fire its updates with monotonic intervals (i. e. 16ms) but the keyboard position can be at this point of time in a different values (it can be 12ms or 20ms or any other value comparing to the previous frame) - see the image below as an example of values captured on simulator:

So in the end I decided to stick to slightly different approach - when CADisplayLink callback is fired, then we read prev frame keyboard position, and instead of calculation duration value based on absolute time intervals we are doing reversing of current keyboard frame, i. e. for a give keyboard position value we are calculating the duration (of animation), and only then calculate next frame as durationFromKeyboardPosition + frameDuration. Such approach gives a decent result on a real device (debug/release, debugger attached/detached etc.).

Last but not least - this PR improves precision for plain keyboard show/hide movements. However on iOS in certain cases animation can be not only CASpringAniamtion - right now I handle it in a PR in a fallback way, i. e. if it's not a spring animation we fallback to the mechanism introduced in https://github.com/kirillzyusko/react-native-keyboard-controller/pull/87 and simply read layer properties.

Later on I'll cover this case as well and will synchronize animations for all types of animations.

[!WARNING] ~~I can not test this PR on ProMotion device because I don't have it at the moment. However I'll get it back after 10.05.24, so I'll test it there and will see if any code adjustments are needed.~~ Attached video proof, that on iPhone 14 Pro animations are running frame in frame.

📢 Changelog

Docs

remove a reference about not perfectly synchronized onMove handler;

E2E

updated assets that were using KeyboardAnimation component;

JS

added gray circle in KeyboardAnimation component which is driven by onMove handler;
in FlatList example -> use onMove handler to handle a case when layout animation is not schedule (when keyboard closed via keyboardShouldPersistTaps)

iOS

added core folder;
added SpringAnimation class;
read animation from layer and try to cast it to CASpringAnimation;
if internal SpringAnimation class is available, then calculate keyboard position using this class;
don't schedule global layout animations anymore since in this case onMove will not be perfectly synchronized in any way (layout animation will override our calculations);

🤔 How Has This Been Tested?

Tested manually on:

iPhone 11 (iOS 17.4.1)
iPhone 6s (iOS 15.8)
iPhone 14 Pro (iOS 17.4) ~~<- I tested it during development, however I made some changes in final code and can not test it again because this device is not with me at the moment - I'll test later when device comes back to me~~
iPhone 15 Pro (iOS 17.4, simulator)