Add new spring feature - clamp

[Latropos]

Summary

Add possibility to define limits that won't be crossed by bouncing spring.
In simplification we can assume that range of bounces is related just with damping ratio,
therefore we recalculate new damping ratio, that satisfies our expectation - the spring moves within its range.

Simplified alghoritm:

1. Calculate $\mathtt{zeta}$ (dampingRatio), $\mathtt{omega1}$ and $\mathtt{omega0}$
2. Calculate such a two values for $\mathtt{zeta}$ that the extrema match both edges of the range exactly
3. Compare the calculate $\mathtt{zeta}$ s with the provided damping ratio. Substitute the damping ratio with the biggest of the values
4. Ignore the fact that now values for $\mathtt{omega0}$ and $\mathtt{omega1}$ are outdated
   • The spring still looks like a real physical one and seems very convincing
5. We changed damping ratio, but the duration stays the same 🥳

Examples

Two examples with different arbitrary chosen config.

Example 1	Example 2
Screen.Recording.2023-10-19.at.14.34.19.mov	Screen.Recording.2023-10-19.at.14.35.53.mov

Test plan

Resting example - code

import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
} from 'react-native-reanimated';
import { View, Text, Button, StyleSheet, ViewStyle } from 'react-native';
import React, { useState } from 'react';

const VIOLET = '#b58df1';
const BORDER_WIDTH = 4;
const FRAME_WIDTH = 300;

const LOWER_CLAMP = 120;
const UPPER_CLAMP = 220;
function renderFramedExample(testedStyle: ViewStyle, description: string) {
  return (
    <>
      <Text style={styles.text}>{description}</Text>
      <View
        style={{
          width: FRAME_WIDTH + 2 * BORDER_WIDTH,
          borderWidth: BORDER_WIDTH,
          borderColor: VIOLET,
        }}>
        <Animated.View
          style={[
            styles.clampMarker,
            { marginBottom: -40, width: UPPER_CLAMP },
          ]}
        />
        <Animated.View style={[styles.movingBox, testedStyle]} />
        <Animated.View
          style={[
            styles.clampMarker,
            {
              marginTop: -40,
              width: FRAME_WIDTH - LOWER_CLAMP,
              alignSelf: 'flex-end',
            },
          ]}
        />
      </View>
    </>
  );
}

export default function AnimatedStyleUpdateExample() {
  const randomWidth = useSharedValue(100);
  const [toggle, setToggle] = useState(false);

  const config = {
    duration: 5000,
    dampingRatio: 0.4,
  };

  const clampedStyle = useAnimatedStyle(() => {
    return {
      width: withSpring(randomWidth.value, {
        ...config,
        clamp: [LOWER_CLAMP, UPPER_CLAMP],
      }),
    };
  });
  const style = useAnimatedStyle(() => {
    return {
      width: withSpring(randomWidth.value, config),
    };
  });

  return (
    <View style={styles.container}>
      {renderFramedExample(clampedStyle, 'Clamp example')}

      {renderFramedExample(style, 'Default')}
      <Button
        title="toggle"
        onPress={() => {
          randomWidth.value = toggle ? 130 : 210;
          setToggle(!toggle);
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    flexDirection: 'column',
    padding: 40,
  },
  clampMarker: {
    margin: 0,
    opacity: 0.5,
    height: 40,
    backgroundColor: VIOLET,
  },
  movingBox: {
    height: 100,
    opacity: 0.5,
    backgroundColor: 'black',
  },
  text: {
    fontSize: 16,
    marginVertical: 4,
  },
});

Documentation

[tomekzaw]

Left some syntax-related comments.

[tomekzaw]

Why do we convert toValue into a number here? Does it mean that we no longer support colors?

[Latropos]

I've just tested and it looks that color handling is a bit buggy with our main code 😱
Something like

 const style = useAnimatedStyle(() => {
    return {
      backgroundColor: withSpring(randomColor.value, config),
    };
  });

where randomColor is a colorname like 'red' or 'blue' doesn't always run (on main!)

Anyway toValue is expected to be a number, since in src/reanimated2/animation/util.ts we have a lot of functions like colorOnStart and numberOnStart that are expected to convert input to numbers and then join it again.

[Latropos]

Also if toValue weren't number it would be difficult wo handle it, since value is always a number.

[Latropos]

Btw. logic inside src/reanimated2/animation/util.ts is very important and complicated, I think I'd suggest splitting it into multiple files, WDYT?

[piaskowyk]

I've tested it and it seems to work 🎉