[docs] Improve Reanimated Swipeable documentation. #3121

latekvo · 2024-09-23T14:07:56Z

Description

Fixed the example provided with the Reanimated Swipeable docs, it looks like a fragment of it was missing.

Also, what's the verdict on this issue?
Today I had to take a look at these docs again and it really occurred to me the way it's currently written can be really confusing.

Here's my proposition, it removes the [0, +] mapping in favour of a verbose explanation:

renderRightActions

accepts a function.
The function receives the following arguments:

progress value representing swiping progress relative to the width of the returned element.
progress is 0 when swipeable is closed, 1 when right action is fully visible.

translation horizontal translation of swipeable in pixels.

swipeable provides an object exposing the methods listed here

This function must return a ReactNode.

side-by-side comparison:

old	new

Of course this change applies to both renderLeftActions and renderRightActions

m-bert · 2024-09-24T06:21:05Z

Also, what's the verdict on #2962 (comment)?

We could use Infinity to make it cleaner. Your suggested version does not say anything about acceptable values and I think it would be better to keep them. However, I'm still not fond of using [0, -], even with Infinity.

latekvo · 2024-09-24T13:24:40Z

I'm still not fond of using [0, -], even with Infinity.

Please let me know if the proposal written in description is ok then, it replaces [0, -] with a regular description of the input-output ranges.

m-bert · 2024-09-24T13:29:44Z

Your suggested version does not say anything about acceptable values and I think it would be better to keep them.

latekvo · 2024-09-24T13:54:53Z

Your suggested version does not say anything about acceptable values and I think it would be better to keep them.

Do either of these work? I think the input-output range is implicitly stated in both of them.

progress value representing swiping progress relative to the width of the returned element.
Equals 0 when swipeable is closed, 1 when right action is open,
and linearly increases to Infinity as right action overshoots it's open position.
progress value representing swiping progress relative to the width of the returned element.
Starts at 0, increases to 1 as right action reaches it's open position,
keeps increasing as right action overshoots it's open position.

m-bert · 2024-09-24T14:57:35Z

What about:

progress value representing swiping progress relative to the width of the returned element.
Equals 0 when swipeable is closed, 1 when right action is open.
Linearly increases to Infinity as right action overshoots it's open position.

?

latekvo · 2024-09-25T08:27:46Z

progress value representing swiping progress relative to the width of the returned element.
Equals 0 when swipeable is closed, 1 when right action is open.
Linearly increases to Infinity as right action overshoots it's open position.

Sounds good, added it in 2967cea

docs/docs/components/reanimated_swipeable.md

src/components/ReanimatedSwipeable.tsx

latekvo · 2024-09-26T08:22:58Z

As of 8c3fd7b added a missing argument description to the docstrings.
Let me know if it's ok

m-bert

Changes to renderLeftActions also apply to renderRightActions 😅 Thanks @kacperkapusciak for help ❤️

docs/docs/components/reanimated_swipeable.md

m-bert · 2024-09-30T08:07:40Z

docs/docs/components/reanimated_swipeable.md


-SharedValue: [startValue, endValue]
+- `progress` value representing swiping progress relative to the width of the returned element.  
+  Equals `0` when `swipeable` is closed, `1` when left action is open.  


Suggested change

Equals `0` when `swipeable` is closed, `1` when left action is open.

Equals `0` when `swipeable` is closed, `1` when `swipeable` is open.

swipeable cannot be open, either the left action or the right action can be open.

Maybe it could be "open to the left" or "open to the right", but i think it's unnecessarily adding additional words, and i'm not sure if it resolves the issue you were referring to.

swipeable cannot be open

Why is that? For example, it has onSwipeableWillOpen and onSwipeableOpen props. What I would change here is I'd use passive voice, i.e.:

Suggested change

Equals `0` when `swipeable` is closed, `1` when left action is open.

Equals `0` when `swipeable` is closed, `1` when `swipeable` is opened.

onSwipeableWillOpen distinguishes between swipeable opening it's left and right element.
Here, the distinction of which side is open is equally necessary.

What about something like this?

Equals 0 when swipeable is closed, 1 when swipeable has its left element open.

or

Equals 0 when swipeable is closed, 1 when the left element is open.

element could be replaced with action, but I think you mentioned you'd prefer to avoid action here, was that a context-specific preference or a general rule?

Here, the distinction of which side is open is equally necessary.

Isn't it implied by the fact that we're in renderLeftActions section?

onSwipeableWillOpen distinguishes between swipeable opening it's left and right element.

Yes it does, but the name indicates that Swipeable itself will be opened. Why can't you say that it is opened if you can say that it is closed?

element could be replaced with action

I think the best we could replace it with would be action panel, as in tsdocs. But still, I believe that Swipeable fits better here. (cc @j-piasecki, @kacperkapusciak)

I agree, if we want to avoid using terms like left/right action, since these are already implied by the function name, then standalone swipeable definitely fits best.

Fixed in df0ff8c throughout 9845471

m-bert · 2024-09-30T08:13:09Z

docs/docs/components/reanimated_swipeable.md

-SharedValue: [startValue, endValue]
+- `progress` value representing swiping progress relative to the width of the returned element.  
+  Equals `0` when `swipeable` is closed, `1` when left action is open.  
+  Linearly increases to `Infinity` as left action overshoots it's open position.


Suggested change

Linearly increases to `Infinity` as left action overshoots it's open position.

When an element overshoots the opened position the value tends towards `Infinity`. Goes back to `1` when `swipeable` is released.

I think the second sentence is a good addition: Goes back to `1` when `swipeable` is released..
But for the first one, i think the original works a bit better, it's shorter and i think the wording it uses is a bit clearer

Perhaps the following would work better?

As left action progress overshoots it's open position, the value linearly increases to Infinity.
Reverts to 1 when swipeable is released.

We wanted to make it as close to natural sentence as possible. Also we'd like to avoid left action, that's why we used element

We wanted to make it as close to natural sentence as possible. Also we'd like to avoid left action, that's why we used element

I believe this is resolved here

Am I missing something, or the only thing that has changed is left action?

Am I missing something, or the only thing that has changed is left action?

I'm not sure which PR you're referencing, in df0ff8c both left and right got replaced.

Are you talking about some PR between df0ff8c and 9845471?

fixed in 620e247

docs/docs/components/reanimated_swipeable.md

…called methods

m-bert · 2024-10-01T15:10:23Z

docs/docs/components/reanimated_swipeable.md


-SharedValue: [startValue, endValue]
+- `progress` - a `SharedValue` representing swiping progress relative to the width of the returned element.
+  - Equals `0` when `swipeable` is closed, `1` when `swipeable` is open.


Suggested change

- Equals `0` when `swipeable` is closed, `1` when `swipeable` is open.

- Equals `0` when `swipeable` is closed, `1` when `swipeable` is opened.

WDYT about passive voice?

Sounds good, will apply it shortly.

Fixed in b93ec82

m-bert

The time has come ⌛

m-bert · 2024-10-02T07:28:37Z

docs/docs/components/reanimated_swipeable.md

@@ -29,7 +29,8 @@ import Swipeable from 'react-native-gesture-handler/ReanimatedSwipeable';

 ### `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".


Suggested change

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".

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".

fixed in 65d1a2b

m-bert · 2024-10-02T07:36:19Z

docs/docs/components/reanimated_swipeable.md

@@ -115,7 +120,8 @@ style object for the children container (Animated.View), for example to apply `f

 ### `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.
+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.


Suggested change

If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture.

If not enabled the gesture will require click + drag, with `enableTrackpadTwoFingerGesture` swiping with two fingers will also trigger the gesture.

fix usage example

8f6c426

latekvo requested review from j-piasecki and m-bert September 23, 2024 14:08

latekvo marked this pull request as ready for review September 23, 2024 14:08

apply renderXActions improvement

2967cea

apply changes to docstrings and improve argument names

c5ed032

j-piasecki reviewed Sep 26, 2024

View reviewed changes

latekvo added 2 commits September 26, 2024 10:18

add the when referring to swipeable

6f68b59

add missing argument description to the docstrings

8c3fd7b

m-bert requested changes Sep 30, 2024

View reviewed changes

latekvo added 7 commits October 1, 2024 13:42

apply function definition description

e37a656

fix docstrings in source code

6cdf23b

Apply suggestions to render___Actions

abf3849

fix references, fix docstring, move one of the render actions bullets

b840aa3

replace left/right action mentions with swipeable, fix punctuation

df0ff8c

improve internal doc structure

3eb201e

make text more neutral where applicable, fix regular functions being …

9845471

…called methods

m-bert reviewed Oct 1, 2024

View reviewed changes

latekvo added 3 commits October 1, 2024 17:55

apply passive voice, other fixes

b93ec82

fix invalid character in docstring preview

449fa48

update tsdocs, update the infinity statement

620e247

m-bert approved these changes Oct 2, 2024

View reviewed changes

m-bert reviewed Oct 2, 2024

View reviewed changes

wrap code and numbers in backticks

65d1a2b

latekvo merged commit f52f6f5 into main Oct 2, 2024
2 checks passed

latekvo deleted the @latekvo/fix-reanimated-swipeable-docs branch October 2, 2024 10:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Improve Reanimated Swipeable documentation. #3121

[docs] Improve Reanimated Swipeable documentation. #3121

latekvo commented Sep 23, 2024

m-bert commented Sep 24, 2024

latekvo commented Sep 24, 2024

m-bert commented Sep 24, 2024

latekvo commented Sep 24, 2024

m-bert commented Sep 24, 2024

latekvo commented Sep 25, 2024

latekvo commented Sep 26, 2024 •

edited

Loading

m-bert left a comment

m-bert Sep 30, 2024

latekvo Sep 30, 2024 •

edited

Loading

m-bert Oct 1, 2024

latekvo Oct 1, 2024

j-piasecki Oct 1, 2024

m-bert Oct 1, 2024

latekvo Oct 1, 2024

m-bert Sep 30, 2024

latekvo Sep 30, 2024

m-bert Oct 1, 2024

latekvo Oct 1, 2024

m-bert Oct 1, 2024

latekvo Oct 1, 2024

latekvo Oct 1, 2024

m-bert Oct 1, 2024

latekvo Oct 1, 2024

latekvo Oct 1, 2024

m-bert left a comment

m-bert Oct 2, 2024

latekvo Oct 2, 2024

m-bert Oct 2, 2024

latekvo Oct 2, 2024

	Equals `0` when `swipeable` is closed, `1` when left action is open.
	Equals `0` when `swipeable` is closed, `1` when `swipeable` is open.

	Linearly increases to `Infinity` as left action overshoots it's open position.
	When an element overshoots the opened position the value tends towards `Infinity`. Goes back to `1` when `swipeable` is released.

	- Equals `0` when `swipeable` is closed, `1` when `swipeable` is open.
	- Equals `0` when `swipeable` is closed, `1` when `swipeable` is opened.

	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".
	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".

	If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture.
	If not enabled the gesture will require click + drag, with `enableTrackpadTwoFingerGesture` swiping with two fingers will also trigger the gesture.

[docs] Improve Reanimated Swipeable documentation. #3121

[docs] Improve Reanimated Swipeable documentation. #3121

Conversation

latekvo commented Sep 23, 2024

Description

renderRightActions

m-bert commented Sep 24, 2024

latekvo commented Sep 24, 2024

m-bert commented Sep 24, 2024

latekvo commented Sep 24, 2024

m-bert commented Sep 24, 2024

latekvo commented Sep 25, 2024

latekvo commented Sep 26, 2024 • edited Loading

m-bert left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

latekvo Sep 30, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-bert left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

`renderRightActions`

latekvo commented Sep 26, 2024 •

edited

Loading

latekvo Sep 30, 2024 •

edited

Loading