Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs page for Reanimated Swipeable #2962

Merged
merged 10 commits into from
Jul 31, 2024
Merged

Add docs page for Reanimated Swipeable #2962

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
0478eb6
add initial docs page for reanimated swipeable
latekvo Jun 26, 2024
7ce9b53
remove deprecated functions, update example, other review suggestions
latekvo Jun 27, 2024
f7dabef
add deprecation note to the old swipeable
latekvo Jun 27, 2024
f16b01e
replace usage of AnimatedValue
latekvo Jun 28, 2024
da42684
add deprecation notice to the old swipeable
latekvo Jun 28, 2024
73e1928
move deprecation notice to constructor
latekvo Jun 28, 2024
526e079
add deprecation docstring to swipeable
latekvo Jul 1, 2024
fdcede8
remove console deprecation warn
latekvo Jul 1, 2024
b829852
encapsulate numbers into code blocks
latekvo Jul 2, 2024
673e037
Change all sentences to use Uppercase first letter
latekvo Jul 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 219 additions & 0 deletions docs/docs/components/reanimated_swipeable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,219 @@
---
id: reanimated_swipeable
title: Reanimated Swipeable
sidebar_label: Reanimated Swipeable
---

import useBaseUrl from '@docusaurus/useBaseUrl';
import GifGallery from '@site/components/GifGallery'

<GifGallery>
<img src={useBaseUrl("gifs/sampleswipeable.gif")} height="120" />
</GifGallery>

:::info
This component is a drop-in replacement for the `Swipeable` component, rewritten using `Reanimated`.
:::

Reanimated `Swipeable` allows for implementing swipeable rows or similar interaction. It renders its children within a panable container allows for horizontal swiping left and right. While swiping one of two "action" containers can be shown depends on whether user swipes left or right (containers can be rendered by `renderLeftActions` or `renderRightActions` props).

### Usage:

To use it, import it in the following way:

```js
import Swipeable from 'react-native-gesture-handler/ReanimatedSwipeable';
```

## Properties

### `friction`

a number that specifies how much the visual interaction will be delayed compared to the gesture distance. e.g. value of 1 will indicate that the swipeable panel should exactly follow the gesture, 2 means it is going to be two times "slower".
latekvo marked this conversation as resolved.
Show resolved Hide resolved

### `leftThreshold`

distance from the left edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width.

### `rightThreshold`

distance from the right edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width.

### `dragOffsetFromLeftEdge`

distance that the panel must be dragged from the left edge to be considered a swipe. The default value is 10.
latekvo marked this conversation as resolved.
Show resolved Hide resolved

### `dragOffsetFromRightEdge`

distance that the panel must be dragged from the right edge to be considered a swipe. The default value is 10.

### `overshootLeft`

a boolean value indicating if the swipeable panel can be pulled further than the left actions panel's width. It is set to `true` by default as long as the left panel render method is present.

### `overshootRight`

a boolean value indicating if the swipeable panel can be pulled further than the right actions panel's width. It is set to `true` by default as long as the right panel render method is present.

### `overshootFriction`

a number that specifies how much the visual interaction will be delayed compared to the gesture distance at overshoot. Default value is 1, it mean no friction, for a native feel, try 8 or above.

### `onSwipeableOpen`

method that is called when action panel gets open (either right or left). Takes swipe direction as
an argument.

### `onSwipeableClose`

method that is called when action panel is closed. Takes swipe direction as
an argument.

### `onSwipeableWillOpen`

method that is called when action panel starts animating on open (either right or left). Takes swipe direction as
an argument.

### `onSwipeableWillClose`

method that is called when action panel starts animating on close. Takes swipe direction as
an argument.

### `renderLeftActions`

method that is expected to return an action panel that is going to be revealed from the left side when user swipes right.
This map describes the values to use as inputRange for extra interpolation:

SharedValue: [startValue, endValue]

progress: [0, 1]

drag: [0, +]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand the [0, +], [0, -] notation

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It means these values travel from 0 to positive infinity and from 0 to negative infinity respectively.
I copied this notation from the legacy Swipeable docs for consistency, but i can write it down differently if you'd prefer.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[0, +] is not that bad, but [0, -] is confusing

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is [0, +∞] and [0, -∞] fine?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I meant is not the infinity sign, but rather the notation of [0, -∞] (it doesn't follow formal definition of interval). I'm not sure though if that is what @kacperkapusciak meant.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey so what's the verdict on this issue?

As far as I see, the formal way would be to note it this way: (-∞, 0] and [0, +∞)
But since here, it represents a mapping from input to output, i think [0, -∞) and [0, +∞) would be more readable.

Please let me know, which one you think would work better @m-bert.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, I don't like [0, -∞) because it looks very unnatural to me. On the other hand I cannot think of any better idea 😞 One could argue that if we only talk about input and output range, we could leave formal notation (but it is not a strong argument)

Anyway, it was @kacperkapusciak who has started this discussion and I want to know what's his stance on this


To support `rtl` flexbox layouts use `flexDirection` styling.

### `renderRightActions`

method that is expected to return an action panel that is going to be revealed from the right side when user swipes left.
This map describes the values to use as inputRange for extra interpolation:

SharedValue: [startValue, endValue]

progress: [0, 1]

drag: [0, -]

To support `rtl` flexbox layouts use `flexDirection` styling.

### `containerStyle`

style object for the container (Animated.View), for example to override `overflow: 'hidden'`.

### `childrenContainerStyle`

style object for the children container (Animated.View), for example to apply `flex: 1`.

### `enableTrackpadTwoFingerGesture` (iOS only)

Enables two-finger gestures on supported devices, for example iPads with trackpads. If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture.

### `mouseButton(value: MouseButton)` (Web & Android only)

Allows users to choose which mouse button should handler respond to. The enum `MouseButton` consists of the following predefined fields:

- `LEFT`
- `RIGHT`
- `MIDDLE`
- `BUTTON_4`
- `BUTTON_5`
- `ALL`

Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`.

### `enableContextMenu(value: boolean)` (Web only)

Specifies whether context menu should be enabled after clicking on underlying view with right mouse button. Default value is set to `false`.

## Methods

Using reference to `Swipeable` it's possible to trigger some actions on it

### `close`

method that closes component.

### `openLeft`

method that opens component on left side.

### `openRight`

method that opens component on right side.

### `reset`

method that resets the swiping states of this `Swipeable` component.

Unlike method `close`, this method does not trigger any animation.

### Example:

See the [swipeable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/release_tests/swipeableReanimation/index.tsx) from GestureHandler Example App.

```jsx
import React, { Component } from 'react';
import { Animated, StyleSheet, View } from 'react-native';
import { RectButton } from 'react-native-gesture-handler';
import Swipeable from 'react-native-gesture-handler/ReanimatedSwipeable';

const LeftAction = ({ dragX, swipeableRef }: LeftActionsProps) => {
const animatedStyle = useAnimatedStyle(() => ({
transform: [
{
translateX: interpolate(
dragX.value,
[0, 50, 100, 101],
[-20, 0, 0, 1],
Extrapolation.CLAMP
),
},
],
}));
return (
<RectButton
style={{
flex: 1,
backgroundColor: '#497AFC',
justifyContent: 'center',
}}
onPress={() => swipeableRef.current!.close()}>
<Animated.Text>
Archive
</Animated.Text>
</RectButton>
);
};

const renderLeftActions = (
_progress: any,
translation: SharedValue<number>,
swipeableRef: React.RefObject<SwipeableMethods>
) => <LeftAction dragX={translation} swipeableRef={swipeableRef} />;

function AppleStyleSwipeableRow({ children }: AppleStyleSwipeableRowProps) {
const swipeableRow = useRef<SwipeableMethods>(null);

return (
<Swipeable
ref={swipeableRow}
friction={2}
enableTrackpadTwoFingerGesture
leftThreshold={30}
renderLeftActions={(_, progress) =>
renderLeftActions(_, progress, swipeableRow)
}>
<Text>Apple style swipeable</Text>
</Swipeable>
);
}
```
61 changes: 33 additions & 28 deletions docs/docs/components/swipeable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@ import GifGallery from '@site/components/GifGallery'
<img src={useBaseUrl("gifs/sampleswipeable.gif")} height="120" />
</GifGallery>

:::caution
This component is deprecated.
Please use [the reanimated version](/react-native-gesture-handler/docs/components/reanimated_swipeable).
:::
latekvo marked this conversation as resolved.
Show resolved Hide resolved

This component allows for implementing swipeable rows or similar interaction. It renders its children within a panable container allows for horizontal swiping left and right. While swiping one of two "action" containers can be shown depends on whether user swipes left or right (containers can be rendered by `renderLeftActions` or `renderRightActions` props).

### Usage:
Expand All @@ -25,60 +30,60 @@ import Swipeable from 'react-native-gesture-handler/Swipeable';

### `friction`

a number that specifies how much the visual interaction will be delayed compared to the gesture distance. e.g. value of 1 will indicate that the swipeable panel should exactly follow the gesture, 2 means it is going to be two times "slower".
A number that specifies how much the visual interaction will be delayed compared to the gesture distance. e.g. value of `1` will indicate that the swipeable panel should exactly follow the gesture, `2` means it is going to be two times "slower".

### `leftThreshold`

distance from the left edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width.
Distance from the left edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width.

### `rightThreshold`

distance from the right edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width.
Distance from the right edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width.

### `dragOffsetFromLeftEdge`

distance that the panel must be dragged from the left edge to be considered a swipe. The default value is 10.
Distance that the panel must be dragged from the left edge to be considered a swipe. The default value is `10`.

### `dragOffsetFromRightEdge`

distance that the panel must be dragged from the right edge to be considered a swipe. The default value is 10.
Distance that the panel must be dragged from the right edge to be considered a swipe. The default value is `10`.

### `overshootLeft`

a boolean value indicating if the swipeable panel can be pulled further than the left actions panel's width. It is set to `true` by default as long as the left panel render method is present.
A boolean value indicating if the swipeable panel can be pulled further than the left actions panel's width. It is set to `true` by default as long as the left panel render method is present.

### `overshootRight`

a boolean value indicating if the swipeable panel can be pulled further than the right actions panel's width. It is set to `true` by default as long as the right panel render method is present.
A boolean value indicating if the swipeable panel can be pulled further than the right actions panel's width. It is set to `true` by default as long as the right panel render method is present.

### `overshootFriction`

a number that specifies how much the visual interaction will be delayed compared to the gesture distance at overshoot. Default value is 1, it mean no friction, for a native feel, try 8 or above.
A number that specifies how much the visual interaction will be delayed compared to the gesture distance at overshoot. Default value is `1`, it mean no friction, for a native feel, try `8` or above.

### `onSwipeableLeftOpen`

:::caution
This callback is deprecated and will be removed in the next version. Please use `onSwipeableOpen(direction)`
:::

method that is called when left action panel gets open.
Method that is called when left action panel gets open.

### `onSwipeableRightOpen`

:::caution
This callback is deprecated and will be removed in the next version. Please use `onSwipeableOpen(direction)`
:::

method that is called when right action panel gets open.
Method that is called when right action panel gets open.

### `onSwipeableOpen`

method that is called when action panel gets open (either right or left). Takes swipe direction as
Method that is called when action panel gets open (either right or left). Takes swipe direction as
an argument.

### `onSwipeableClose`

method that is called when action panel is closed. Takes swipe direction as
Method that is called when action panel is closed. Takes swipe direction as
an argument.

### `onSwipeableLeftWillOpen`
Expand All @@ -87,55 +92,55 @@ an argument.
This callback is deprecated and will be removed in the next version. Please use `onSwipeableWillOpen(direction)`
:::

method that is called when left action panel starts animating on open.
Method that is called when left action panel starts animating on open.

### `onSwipeableRightWillOpen`

:::caution
This callback is deprecated and will be removed in the next version. Please use `onSwipeableWillOpen(direction)`
:::

method that is called when right action panel starts animating on open.
Method that is called when right action panel starts animating on open.

### `onSwipeableWillOpen`

method that is called when action panel starts animating on open (either right or left). Takes swipe direction as
Method that is called when action panel starts animating on open (either right or left). Takes swipe direction as
an argument.

### `onSwipeableWillClose`

method that is called when action panel starts animating on close. Takes swipe direction as
Method that is called when action panel starts animating on close. Takes swipe direction as
an argument.

### `renderLeftActions`

method that is expected to return an action panel that is going to be revealed from the left side when user swipes right.
Method that is expected to return an action panel that is going to be revealed from the left side when user swipes right.
This map describes the values to use as inputRange for extra interpolation:
AnimatedValue: [startValue, endValue]

progressAnimatedValue: [0, 1]
dragAnimatedValue: [0, +]
progressAnimatedValue: `[0, 1]`
dragAnimatedValue: `[0, +]`

To support `rtl` flexbox layouts use `flexDirection` styling.

### `renderRightActions`

method that is expected to return an action panel that is going to be revealed from the right side when user swipes left.
Method that is expected to return an action panel that is going to be revealed from the right side when user swipes left.
This map describes the values to use as inputRange for extra interpolation:
AnimatedValue: [startValue, endValue]

progressAnimatedValue: [0, 1]
dragAnimatedValue: [0, -]
progressAnimatedValue: `[0, 1]`
dragAnimatedValue: `[0, -]`

To support `rtl` flexbox layouts use `flexDirection` styling.

### `containerStyle`

style object for the container (Animated.View), for example to override `overflow: 'hidden'`.
Style object for the container (Animated.View), for example to override `overflow: 'hidden'`.

### `childrenContainerStyle`

style object for the children container (Animated.View), for example to apply `flex: 1`.
Style object for the children container (Animated.View), for example to apply `flex: 1`.

### `enableTrackpadTwoFingerGesture` (iOS only)

Expand Down Expand Up @@ -164,19 +169,19 @@ Using reference to `Swipeable` it's possible to trigger some actions on it

### `close`

method that closes component.
Method that closes component.

### `openLeft`

method that opens component on left side.
Method that opens component on left side.

### `openRight`

method that opens component on right side.
Method that opens component on right side.

### `reset`

method that resets the swiping states of this `Swipeable` component.
Method that resets the swiping states of this `Swipeable` component.

Unlike method `close`, this method does not trigger any animation.

Expand Down
Loading
Loading