feat(item-sliding): modern animation to reveal options

[sean-perkins]

trafficstars

Issue number: Internal

---

What is the current behavior?

Currently when swiping to reveal options, the options are translated along with the swipe distance to reveal the last to first option.

https://github.com/ionic-team/ionic-framework/assets/13732623/084cefb8-9ac0-4f37-a4be-d8cddc7ee847

This is different than the behavior we observe in iOS 17 and Material Design, where the options are all revealed at a consistent interval with the swipe distance.

What is the new behavior?

Item Sliding

• There is a new property called animationType available on ion-item-sliding to customize the animation behavior of the sliding item options.
  • animationType="legacy" will maintain the previous animation behavior that developers expect in their applications in Ionic v7.
  • animationType="modern" will opt-in to the modern animation appearance as seen in iOS 17. This animation does leverage the Web Animation API and developers should consult caniuse if targeting older devices. If Web Animations API is not supported on the device, the sliding item will fallback to the legacy implementation and log a warning to the console.

LTR	RTL

Ionic Animations

To support the animation behavior of this feature, the Ionic Animations utility was updated to add support for commitStyles. This feature reflects the state of styles from the animation to the element node. This enables parsing the computed transformations to leverage in the animation. The styles assigned by the Web Animations API take priority over the reflected state.

The constants for detecting if the environment supports the Web Animations API have been exported.

Does this introduce a breaking change?

• [ ] Yes
• [x] No

Other information

Verifying this PR

1. Test on a physical device or mobile emulator.
2. Verify that swiping to reveal options represents the preview above, where option are all revealed gradually with the swipe distance.
3. Verify the same behavior in RTL mode.
4. Verify the release and cancel behavior with quickly swiping to show/collapse items as well as releasing the swipe gesture prior to the threshold that shows/collapses the item.

Deep dive into the implementation

This deep dive focuses on the item options animation within this PR. It assumes you are familiar to how the existing item sliding animation behaves to translate the item to reveal options.

1. Prepare item options for animation

In order to simplify the calculations of the animation, we relocate each item option off the visible viewport to be on the edge of the screen. For example in LTR text direction, the items on the end of the container will be located on the right edge of the screen, off the viewport.

This image demonstrates the transformation on the x-axis to move the end options in LTR text decoration.

To determine the distance to move each option, we need to define some initial values and their purposes:

• o: This is an incrementing value that accounts for the total width of all previous processed item options. For example when it processes the first item option, this resolves 0, the next item option this would equal the width of the previous item option. On the next item option this would equal the width of the two previous item options and so on.
• tW: The total width of all the item options.
• oW: The width of the current item option.

With this information we can equate the distance as follows:

Side: Start

• Left-to-right text decoration: distance = -1 * (oW + o)
• Right-to-left text decoration: distance = -1 * (tw - o)

Side: End

• Left-to-right text decoration: distance = tW - o
• Right-to-left text decoration: distance = o + oW

2. Animate each option during swipe gesture

As the user swipes to reveal options, there is an open amount of space to reveal all the options. We need to give each option roughly the same amount of visible viewport space.

This image demonstrates the transformation on the x-axis to move each option into the visible open space from the swipe gesture. This graphic is representative of end item options in LTR. The stacking order of the elements is important to note, so that items option are pulled from underneath each other.

We are able to defer the complexity of computing the transform value as the user is dragging the item to the Web Animations API by transforming between two fixed points: the position off the viewport and the original render position, and animate based on the progress of the open amount divided by the options total width.

As a result of using a transform between two points, the amount of space that each option fills in the available space will be dependent on the width of the option. The animation effect scales evenly with options of equal width.

[thetaPC]

Dev build: 7.6.2-dev.11705694334.11b34c62