docs: add more information about onCancel property (#4659)

* chore: update the tsdocs * docs: add more clear description about `onCancel` * chore: add changeset * fix: update .changeset/forty-months-hang.md Co-authored-by: Ali Emir Şen <[email protected]> * docs: fix typos --------- Co-authored-by: Ali Emir Şen <[email protected]>
refinedev · Jul 13, 2023 · 3af9989 · 3af9989
1 parent 5da81a1
commit 3af9989
Show file tree

Hide file tree

Showing 9 changed files with 239 additions and 50 deletions.
diff --git a/.changeset/forty-months-hang.md b/.changeset/forty-months-hang.md
@@ -0,0 +1,10 @@
+---
+"@refinedev/core": patch
+---
+
+chore: fix tsdoc description of `onCancel` property on following hooks:
+
+- `useUpdate`
+- `useUpdateMany`
+- `useDelete`
+- `useDeleteMany`
diff --git a/documentation/docs/api-reference/core/hooks/data/useDelete/index.md b/documentation/docs/api-reference/core/hooks/data/useDelete/index.md
@@ -93,7 +93,7 @@ mutate(
 ### `overtimeOptions`
 
 If you want loading overtime for the request, you can pass the `overtimeOptions` prop to the this hook. It is useful when you want to show a loading indicator when the request takes too long.
-`interval` is the time interval in milliseconds. `onInterval` is the function that will be called on each interval. 
+`interval` is the time interval in milliseconds. `onInterval` is the function that will be called on each interval.
 
 Return `overtime` object from this hook. `elapsedTime` is the elapsed time in milliseconds. It becomes `undefined` when the request is completed.
 
@@ -105,14 +105,15 @@ const { overtime } = useDelete({
  onInterval(elapsedInterval) {
  console.log(elapsedInterval);
  },
- }
+ },
 });
 
 console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
 
 // You can use it like this:
 {elapsedTime >= 4000 && <div>this takes a bit longer than expected</div>}
 ```
+
 ## Mutation Parameters
 
 ### `resource` <PropTag required />
@@ -175,18 +176,39 @@ mutate({
 
 ### `onCancel`
 
-When `mutationMode` is set to `undoable`, `onCancel` is used to determine what to do when the user cancels the mutation.
+The `onCancel` property can be utilized when the `mutationMode` is set to `"undoable"`. It provides a function that can be used to cancel the ongoing mutation.
+
+By defining `onCancel`, undoable notification will not be shown automatically. This gives you the flexibility to handle the cancellation process in your own way, such as showing a custom notification or implementing any other desired behavior to allow users to cancel the mutation.
 
 ```tsx
-const { mutate } = useDelete();
+import { useRef } from "react";
+import { useDelete } from "@refinedev/core";
 
-mutate({
- mutationMode: "undoable",
- onCancel: (cancelMutation) => {
- cancelMutation();
- // you can do something else here
- },
-});
+const MyComponent = () => {
+ const { mutate } = useDelete();
+ const cancelRef = useRef<(() => void) | null>(null);
+
+ const deleteItem = () => {
+ mutate({
+ //...
+ mutationMode: "undoable",
+ onCancel: (cancelMutation) => {
+ cancelRef.current = cancelMutation;
+ },
+ });
+ };
+
+ const cancelDelete = () => {
+ cancelRef.current?.();
+ };
+
+ return (
+ <>
+ <button onClick={deleteItem}>Delete</button>
+ <button onClick={cancelDelete}>Cancel</button>
+ </>
+ );
+};
 ```
 
 ### `successNotification`
@@ -314,6 +336,7 @@ Returns an object with TanStack Query's `useMutation` return values.
 > For more information, refer to the [`useMutation` documentation &#8594](https://tanstack.com/query/v4/docs/react/reference/useMutation)
 
 ### Additional Values
+
 #### `overtime`
 
 `overtime` object is returned from this hook. `elapsedTime` is the elapsed time in milliseconds. It becomes `undefined` when the request is completed.
@@ -323,6 +346,7 @@ const { overtime } = useDelete();
 
 console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
 ```
+
 ## API
 
 ### Mutation Parameters
@@ -333,7 +357,7 @@ console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
 | id <div className=" required">Required</div> | id for mutation function | [`BaseKey`](/api-reference/core/interfaces.md#basekey) | |
 | mutationMode | [Determines when mutations are executed](/advanced-tutorials/mutation-mode.md) | ` "pessimistic` \| `"optimistic` \| `"undoable"` | `"pessimistic"`\* |
 | undoableTimeout | Duration to wait before executing the mutation when `mutationMode = "undoable"` | `number` | `5000ms`\* |
-| onCancel | Callback that runs when undo button is clicked on `mutationMode = "undoable"` | `(cancelMutation: () => void) => void` | |
+| onCancel | Provides a function to cancel the mutation when `mutationMode = "undoable"`  | `(cancelMutation: () => void) => void` | |
 | successNotification | Successful Mutation notification | [`SuccessErrorNotification`](/api-reference/core/interfaces.md#successerrornotification) | "Successfully deleted a `resource`" |
 | errorNotification | Unsuccessful Mutation notification | [`SuccessErrorNotification`](/api-reference/core/interfaces.md#successerrornotification) | "Error (status code: `status`" |
 | meta | Meta data query for `dataProvider` | [`MetaDataQuery`](/api-reference/core/interfaces.md#metadataquery) | {} |

diff --git a/documentation/docs/api-reference/core/hooks/data/useDeleteMany/index.md b/documentation/docs/api-reference/core/hooks/data/useDeleteMany/index.md
@@ -89,7 +89,7 @@ mutate(
 ### `overtimeOptions`
 
 If you want loading overtime for the request, you can pass the `overtimeOptions` prop to the this hook. It is useful when you want to show a loading indicator when the request takes too long.
-`interval` is the time interval in milliseconds. `onInterval` is the function that will be called on each interval. 
+`interval` is the time interval in milliseconds. `onInterval` is the function that will be called on each interval.
 
 Return `overtime` object from this hook. `elapsedTime` is the elapsed time in milliseconds. It becomes `undefined` when the request is completed.
 
@@ -101,14 +101,15 @@ const { overtime } = useDeleteMany({
  onInterval(elapsedInterval) {
  console.log(elapsedInterval);
  },
- }
+ },
 });
 
 console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
 
 // You can use it like this:
 {elapsedTime >= 4000 && <div>this takes a bit longer than expected</div>}
 ```
+
 ## Mutation Parameters
 
 ### `resource` <PropTag required />
@@ -171,18 +172,39 @@ mutate({
 
 ### `onCancel`
 
-When `mutationMode` is set to `undoable`, `onCancel` is used to determine what to do when the user cancels the mutation.
+The `onCancel` property can be utilized when the `mutationMode` is set to `"undoable"`. It provides a function that can be used to cancel the ongoing mutation.
+
+By defining `onCancel`, undoable notification will not be shown automatically. This gives you the flexibility to handle the cancellation process in your own way, such as showing a custom notification or implementing any other desired behavior to allow users to cancel the mutation.
 
 ```tsx
-const { mutate } = useDeleteMany();
+import { useRef } from "react";
+import { useDeleteMany } from "@refinedev/core";
 
-mutate({
- mutationMode: "undoable",
- onCancel: (cancelMutation) => {
- cancelMutation();
- // you can do something else here
- },
-});
+const MyComponent = () => {
+ const { mutate } = useDeleteMany();
+ const cancelRef = useRef<(() => void) | null>(null);
+
+ const deleteItems = () => {
+ mutate({
+ //...
+ mutationMode: "undoable",
+ onCancel: (cancelMutation) => {
+ cancelRef.current = cancelMutation;
+ },
+ });
+ };
+
+ const cancelDelete = () => {
+ cancelRef.current?.();
+ };
+
+ return (
+ <>
+ <button onClick={deleteItems}>Delete</button>
+ <button onClick={cancelDelete}>Cancel</button>
+ </>
+ );
+};
 ```
 
 ### `successNotification`
@@ -311,6 +333,7 @@ Returns an object with TanStack Query's `useMutation` return values.
 > For more information, refer to the [`useMutation` documentation &#8594](https://tanstack.com/query/v4/docs/react/reference/useMutation)
 
 ### Additional Values
+
 #### `overtime`
 
 `overtime` object is returned from this hook. `elapsedTime` is the elapsed time in milliseconds. It becomes `undefined` when the request is completed.
@@ -331,7 +354,7 @@ console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
 | ids <div className=" required">Required</div> | ids for mutation function | [`BaseKey[]`](/api-reference/core/interfaces.md#basekey) | |
 | mutationMode | [Determines when mutations are executed](/advanced-tutorials/mutation-mode.md) | ` "pessimistic` \| `"optimistic` \| `"undoable"` | `"pessimistic"`\* |
 | undoableTimeout | Duration to wait before executing the mutation when `mutationMode = "undoable"` | `number` | `5000ms`\* |
-| onCancel | Callback that runs when undo button is clicked on `mutationMode = "undoable"` | `(cancelMutation: () => void) => void` | |
+| onCancel | Provides a function to cancel the mutation when `mutationMode = "undoable"`  | `(cancelMutation: () => void) => void` | |
 | successNotification | Successful Mutation notification | [`SuccessErrorNotification`](/api-reference/core/interfaces.md#successerrornotification) | "Successfully deleted `resource`" |
 | errorNotification | Unsuccessful Mutation notification | [`SuccessErrorNotification`](/api-reference/core/interfaces.md#successerrornotification) | "Error when updating `resource` (status code: `statusCode`)" |
 | meta | Meta data query for `dataProvider` | [`MetaDataQuery`](/api-reference/core/interfaces.md#metadataquery) | {} |

diff --git a/documentation/docs/api-reference/core/hooks/data/useUpdate/index.md b/documentation/docs/api-reference/core/hooks/data/useUpdate/index.md
@@ -174,18 +174,39 @@ mutate({
 
 ### `onCancel`
 
-When `mutationMode` is set to `undoable`, `onCancel` is used to determine what to do when the user cancels the mutation.
+The `onCancel` property can be utilized when the `mutationMode` is set to `"undoable"`. It provides a function that can be used to cancel the ongoing mutation.
+
+By defining `onCancel`, undoable notification will not be shown automatically. This gives you the flexibility to handle the cancellation process in your own way, such as showing a custom notification or implementing any other desired behavior to allow users to cancel the mutation.
 
 ```tsx
-const { mutate } = useUpdate();
+import { useRef } from "react";
+import { useUpdate } from "@refinedev/core";
 
-mutate({
- mutationMode: "undoable",
- onCancel: (cancelMutation) => {
- cancelMutation();
- // you can do something else here
- },
-});
+const MyComponent = () => {
+ const { mutate } = useUpdate();
+ const cancelRef = useRef<(() => void) | null>(null);
+
+ const updateItem = () => {
+ mutate({
+ //...
+ mutationMode: "undoable",
+ onCancel: (cancelMutation) => {
+ cancelRef.current = cancelMutation;
+ },
+ });
+ };
+
+ const cancelUpdate = () => {
+ cancelRef.current?.();
+ };
+
+ return (
+ <>
+ <button onClick={updateItem}>Update</button>
+ <button onClick={cancelUpdate}>Cancel</button>
+ </>
+ );
+};
 ```
 
 ### `successNotification`
@@ -306,10 +327,11 @@ mutate({
  invalidates: ["list", "many", "detail"],
 });
 ```
+
 ### `overtimeOptions`
 
 If you want loading overtime for the request, you can pass the `overtimeOptions` prop to the this hook. It is useful when you want to show a loading indicator when the request takes too long.
-`interval` is the time interval in milliseconds. `onInterval` is the function that will be called on each interval. 
+`interval` is the time interval in milliseconds. `onInterval` is the function that will be called on each interval.
 
 Return `overtime` object from this hook. `elapsedTime` is the elapsed time in milliseconds. It becomes `undefined` when the request is completed.
 
@@ -321,21 +343,23 @@ const { overtime } = useUpdate({
  onInterval(elapsedInterval) {
  console.log(elapsedInterval);
  },
- }
+ },
 });
 
 console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
 
 // You can use it like this:
 {elapsedTime >= 4000 && <div>this takes a bit longer than expected</div>}
 ```
+
 ## Return Values
 
 Returns an object with TanStack Query's `useMutation` return values.
 
 > For more information, refer to the [`useMutation` documentation &#8594](https://tanstack.com/query/v4/docs/react/reference/useMutation)
 
 ### Additional Values
+
 #### `overtime`
 
 `overtime` object is returned from this hook. `elapsedTime` is the elapsed time in milliseconds. It becomes `undefined` when the request is completed.
@@ -345,6 +369,7 @@ const { overtime } = useUpdate();
 
 console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
 ```
+
 ## API
 
 ### Mutation Parameters
@@ -356,7 +381,7 @@ console.log(overtime.elapsedTime); // undefined, 1000, 2000, 3000 4000, ...
 | values <div className=" required">Required</div> | Values for mutation function | `TVariables` | {} |
 | mutationMode | [Determines when mutations are executed](/advanced-tutorials/mutation-mode.md) | ` "pessimistic` \| `"optimistic` \| `"undoable"` | `"pessimistic"`\* |
 | undoableTimeout | Duration to wait before executing the mutation when `mutationMode = "undoable"` | `number` | `5000ms`\* |
-| onCancel | Callback that runs when undo button is clicked on `mutationMode = "undoable"` | `(cancelMutation: () => void) => void` | |
+| onCancel | Provides a function to cancel the mutation when `mutationMode = "undoable"`  | `(cancelMutation: () => void) => void` | |
 | successNotification | Successful Mutation notification | [`SuccessErrorNotification`](/api-reference/core/interfaces.md#successerrornotification) | "Successfully updated `resource`" |
 | errorNotification | Unsuccessful Mutation notification | [`SuccessErrorNotification`](/api-reference/core/interfaces.md#successerrornotification) | "Error when updating `resource` (status code: `statusCode`)" |
 | meta | Meta data query for `dataProvider` | [`MetaDataQuery`](/api-reference/core/interfaces.md#metadataquery) | {} |