react-swipe-action 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +167 -12
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,15 @@
1
- # React swipe action [![npm](https://img.shields.io/npm/v/react-swipe-action.svg)](https://www.npmjs.com/package/react-swipe-action) ![npm type definitions](https://img.shields.io/npm/types/react-swipe-action.svg)
1
+ # React Swipe Action [![npm](https://img.shields.io/npm/v/react-swipe-action.svg)](https://www.npmjs.com/package/react-swipe-action) ![npm type definitions](https://img.shields.io/npm/types/react-swipe-action.svg)
2
2
 
3
- Swipe to reveal or perform an action. Try interactive [Storybook demo](https://filipchalupa.cz/react-swipe-action/).
3
+ Swipe to reveal or perform an action. Try the interactive [Storybook demo](https://filipchalupa.cz/react-swipe-action/).
4
+
5
+ ## Features
6
+
7
+ - Works with both mouse and touch events.
8
+ - Supports actions on both the left (start) and right (end) sides.
9
+ - "Long swipe" gesture to trigger an action.
10
+ - Customizable content and backgrounds for each side.
11
+ - `useSwipeActionReset` hook to programmatically close the swipe action.
12
+ - Written in TypeScript.
4
13
 
5
14
  ## Installation
6
15
 
@@ -10,28 +19,174 @@ npm install react-swipe-action
10
19
 
11
20
  ## How to use
12
21
 
22
+ Import the component and the CSS file.
23
+
13
24
  ```jsx
14
25
  import { SwipeAction } from 'react-swipe-action'
15
26
  import 'react-swipe-action/dist/index.css'
27
+ ```
28
+
29
+ Use the `SwipeAction` component. The `main` prop is a function that receives a `handle` which you should pass to the element you want to be draggable.
30
+
31
+ ```jsx
32
+ <SwipeAction
33
+ main={(handle) => (
34
+ <div className="main-content">
35
+ Swipe me
36
+ {handle}
37
+ </div>
38
+ )}
39
+ startAction={...}
40
+ endAction={...}
41
+ />
42
+ ```
43
+
44
+ ### Actions
45
+
46
+ You can define `startAction` (swipe from left to right) and/or `endAction` (swipe from right to left).
47
+
48
+ An action is an object with the following properties:
49
+
50
+ - `content`: The content to be revealed (e.g., a button).
51
+ - `background`: The background that is shown behind the content.
52
+ - `onLongSwipe`: A function to be called when a "long swipe" is performed.
53
+
54
+ Action and its properties are optional, so you can choose to only implement one side or just the long swipe.
55
+
56
+ ```jsx
57
+ <SwipeAction
58
+ main={(handle) => <button>Main content{handle}</button>}
59
+ endAction={{
60
+ content: <button onClick={() => alert('Action clicked!')}>Delete</button>,
61
+ background: <div style={{ backgroundColor: 'red' }} />,
62
+ onLongSwipe: () => alert('Long swipe!'),
63
+ }}
64
+ />
65
+ ```
66
+
67
+ ### Closing the action programmatically
68
+
69
+ You can use the `useSwipeActionReset` hook to get a function that will reset the swipe action to its initial state. This is useful when you want to close the action after a button is clicked.
70
+
71
+ ```jsx
72
+ import { SwipeAction, useSwipeActionReset } from 'react-swipe-action'
73
+
74
+ const ActionButton = ({ onClick, children }) => {
75
+ const reset = useSwipeActionReset()
76
+ return (
77
+ <button
78
+ onClick={async () => {
79
+ await onClick()
80
+ reset()
81
+ }}
82
+ >
83
+ {children}
84
+ </button>
85
+ )
86
+ }
87
+
88
+ // ...
89
+
90
+ ;<SwipeAction
91
+ // ...
92
+ endAction={{
93
+ content: (
94
+ <ActionButton onClick={() => alert('Deleted!')}>Delete</ActionButton>
95
+ ),
96
+ // ...
97
+ }}
98
+ />
99
+ ```
100
+
101
+ ## API
102
+
103
+ ### `<SwipeAction />` Props
104
+
105
+ | Prop | Type | Description |
106
+ | ------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
107
+ | `main` | `(handle: ReactNode) => ReactNode` | **Required.** A function that returns the main content. It receives a `handle` which should be rendered on the draggable element. |
108
+ | `startAction` | `Action` | An action to be performed when swiping from left to right. |
109
+ | `endAction` | `Action` | An action to be performed when swiping from right to left. |
110
+
111
+ ### `Action` Type
112
+
113
+ | Prop | Type | Description |
114
+ | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
115
+ | `content` | `ReactNode` | The content to be revealed when swiping. |
116
+ | `background` | `ReactNode` | The background to be shown behind the content. |
117
+ | `onLongSwipe` | `() => void` | A callback function that is triggered on a "long swipe" gesture. This can be used for quick actions without revealing the content. |
118
+
119
+ ### `useSwipeActionReset()`
120
+
121
+ A custom hook that returns a `reset` function. Call `reset()` to programmatically close the swipe action.
122
+
123
+ ## Example
124
+
125
+ ```jsx
126
+ import { SwipeAction, useSwipeActionReset } from 'react-swipe-action'
127
+ import 'react-swipe-action/dist/index.css'
128
+
129
+ const pretendWork = () => new Promise((resolve) => setTimeout(resolve, 1000))
130
+
131
+ const ActionButton = ({ onClick, children }) => {
132
+ const reset = useSwipeActionReset()
133
+ return (
134
+ <button
135
+ onClick={async () => {
136
+ await onClick()
137
+ reset()
138
+ }}
139
+ >
140
+ {children}
141
+ </button>
142
+ )
143
+ }
16
144
 
17
145
  const App = () => {
18
146
  return (
19
147
  <SwipeAction
20
- main={(handle) => <button onClick={() => { alert('Click') }} style={{ position: 'relative' }}>
21
- Button
22
- {handle}
23
- </button>}
148
+ main={(handle) => (
149
+ <button
150
+ className="main"
151
+ onClick={() => {
152
+ alert("You've clicked me!")
153
+ }}
154
+ >
155
+ Swipe me
156
+ {handle}
157
+ </button>
158
+ )}
159
+ startAction={{
160
+ content: (
161
+ <ActionButton
162
+ onClick={() => {
163
+ alert('Click left side!')
164
+ }}
165
+ >
166
+ 🔖
167
+ </ActionButton>
168
+ ),
169
+ background: <div style={{ backgroundColor: 'blue' }} />,
170
+ onLongSwipe: () => {
171
+ alert('Long swipe from left side!')
172
+ },
173
+ }}
24
174
  endAction={{
25
175
  content: (
26
- <button
27
- type="button"
28
- onClick={() => { alert('Right action') }}
176
+ <ActionButton
177
+ onClick={async () => {
178
+ await pretendWork()
179
+ alert('Click right side which took some time to process!')
180
+ }}
29
181
  >
30
- Right action
31
- </button>
182
+ 🗑️
183
+ </ActionButton>
32
184
  ),
33
- onLongSwipe: () => { alert('Right action') },
34
185
  background: <div style={{ backgroundColor: 'red' }} />,
186
+ onLongSwipe: async () => {
187
+ await pretendWork()
188
+ alert('Long swipe from right side which took some time to process!')
189
+ },
35
190
  }}
36
191
  />
37
192
  )
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "react-swipe-action",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Swipe to reveal or perform an action.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",