docs(core): add button hook docs (#5817)

documentation/docs/core/hooks/utilities/buttons/index.md

@@ -0,0 +1,183 @@
+---
+title: Buttons
+source: packages/core/src/hooks/button
+---
+
+Refine offers a set of buttons in UI integrations that you can use to perform actions like navigation, deletion and refresh. These buttons include many useful features such as confirmation dialogs, access control, i18n and inferring parameters from the current route.
+
+All these buttons are powered by respective hooks that you can use to create your own custom buttons or customizing the existing ones without having to write the logic from scratch.
+
+## Hooks
+
+### useListButton
+
+`useListButton` provides set of values to be used for navigating to a list view of a resource.
+
+```ts
+const {
+  to, // The path to navigate to.
+  label, // The label to be displayed on the button.
+  title, // If the button is disabled, the title will contain the reason for the button being disabled.
+  hidden, // Whether the button should be hidden or not.
+  disabled, // Whether the button should be disabled or not.
+  LinkComponent, // The component to be used as a link. This is provided by the router provider from `<Refine />`.
+} = useListButton({
+  resource: "posts", // Resource name/identifier, if not provided, it will be inferred from the current route.
+  accessControl, // To enable/disable the access control checks and hide/disable the button based on the permissions.
+  meta, // Meta object to be passed to the navigation. This can be used to pass additional parameters to the route if needed.
+});
+```
+
+### useCreateButton
+
+`useCreateButton` provides set of values to be used for navigating to a create view of a resource.
+
+```ts
+const {
+  to, // The path to navigate to.
+  label, // The label to be displayed on the button.
+  title, // If the button is disabled, the title will contain the reason for the button being disabled.
+  hidden, // Whether the button should be hidden or not.
+  disabled, // Whether the button should be disabled or not.
+  LinkComponent, // The component to be used as a link. This is provided by the router provider from `<Refine />`.
+} = useCreateButton({
+  resource: "posts", // Resource name/identifier, if not provided, it will be inferred from the current route.
+  accessControl, // To enable/disable the access control checks and hide/disable the button based on the permissions.
+  meta, // Meta object to be passed to the navigation. This can be used to pass additional parameters to the route if needed.
+});
+```
+
+### useShowButton
+
+`useShowButton` provides set of values to be used for navigating to a show view of a resource for a given record.
+
+```ts
+const {
+  to, // The path to navigate to.
+  label, // The label to be displayed on the button.
+  title, // If the button is disabled, the title will contain the reason for the button being disabled.
+  hidden, // Whether the button should be hidden or not.
+  disabled, // Whether the button should be disabled or not.
+  LinkComponent, // The component to be used as a link. This is provided by the router provider from `<Refine />`.
+} = useShowButton({
+  resource: "posts", // Resource name/identifier, if not provided, it will be inferred from the current route.
+  id, // Record identifier to navigate to the show view. If not provided, it will be inferred from the current route.
+  accessControl, // To enable/disable the access control checks and hide/disable the button based on the permissions.
+  meta, // Meta object to be passed to the navigation. This can be used to pass additional parameters to the route if needed.
+});
+```
+
+### useEditButton
+
+`useEditButton` provides set of values to be used for navigating to an edit view of a resource for a given record.
+
+```ts
+const {
+  to, // The path to navigate to.
+  label, // The label to be displayed on the button.
+  title, // If the button is disabled, the title will contain the reason for the button being disabled.
+  hidden, // Whether the button should be hidden or not.
+  disabled, // Whether the button should be disabled or not.
+  LinkComponent, // The component to be used as a link. This is provided by the router provider from `<Refine />`.
+} = useEditButton({
+  resource: "posts", // Resource name/identifier, if not provided, it will be inferred from the current route.
+  id, // Record identifier to navigate to the edit view. If not provided, it will be inferred from the current route.
+  accessControl, // To enable/disable the access control checks and hide/disable the button based on the permissions.
+  meta, // Meta object to be passed to the navigation. This can be used to pass additional parameters to the route if needed.
+});
+```
+
+### useCloneButton
+
+`useCloneButton` provides set of values to be used for navigating to a clone view of a resource for a given record.
+
+```ts
+const {
+  to, // The path to navigate to.
+  label, // The label to be displayed on the button.
+  title, // If the button is disabled, the title will contain the reason for the button being disabled.
+  hidden, // Whether the button should be hidden or not.
+  disabled, // Whether the button should be disabled or not.
+  LinkComponent, // The component to be used as a link. This is provided by the router provider from `<Refine />`.
+} = useCloneButton({
+  resource: "posts", // Resource name/identifier, if not provided, it will be inferred from the current route.
+  id, // Record identifier to navigate to the clone view. If not provided, it will be inferred from the current route.
+  accessControl, // To enable/disable the access control checks and hide/disable the button based on the permissions.
+  meta, // Meta object to be passed to the navigation. This can be used to pass additional parameters to the route if needed.
+});
+```
+
+### useDeleteButton
+
+`useDeleteButton` provides set of values to be used for deleting a record. This hook will also provide labels for the confirmation dialog.
+
+```ts
+const {
+  onConfirm, // The function to be called when the user confirms the deletion. This will call the mutation of `useDelete` under the hood.
+  label, // The label to be displayed on the button.
+  title, // If the button is disabled, the title will contain the reason for the button being disabled.
+  disabled, // Whether the button should be disabled or not.
+  hidden, // Whether the button should be hidden or not.
+  loading, // Whether the button should be in loading state or not.
+  confirmTitle, // The title of the confirmation dialog.
+  confirmOkLabel, // The label of the confirmation dialog's confirm button.
+  cancelLabel, // The label of the confirmation dialog's cancel button.
+} = useDeleteButton({
+  resource, // Resource name/identifier, if not provided, it will be inferred from the current route.
+  id, // Record identifier to delete. If not provided, it will be inferred from the current route.
+  onSuccess, // The function to be called when the deletion is successful.
+  mutationMode, // The mode of the mutation. If not passed, globally defined mutation mode will be used.
+  successNotification, // The notification to be shown when the deletion is successful.
+  errorNotification, // The notification to be shown when the deletion fails.
+  accessControl, // To enable/disable the access control checks and hide/disable the button based on the permissions.
+  meta, // Meta object to be passed to the deletion.
+  dataProviderName, // The name of the data provider to be used for the deletion. If not provided, the default data provider will be used.
+  invalidates, // The list of scopes of a resource to be invalidated after the deletion.
+});
+```
+
+### useRefreshButton
+
+`useRefreshButton` provides set of values to be used for refreshing the record of a resource.
+
+```ts
+const {
+  onClick, // The function to be called when the user clicks the button. This will trigger an invalidation of the query cache.
+  label, // The label to be displayed on the button.
+  loading, // Whether the button should be in loading state or not.
+} = useRefreshButton({
+  resource, // Resource name/identifier, if not provided, it will be inferred from the current route.
+  id, // Record identifier to refresh. If not provided, it will be inferred from the current route.
+  dataProviderName, // The name of the data provider to be used for the refresh. If not provided, the default data provider will be used.
+});
+```
+
+### useSaveButton
+
+`useSaveButton` provides a label for a save button that can be used in forms. Props related to submission of the form will be provided by the [`useForm`](/docs/data/hooks/use-form) hook.
+
+```ts
+const {
+  label, // The label to be displayed on the button.
+} = useSaveButton();
+```
+
+### useExportButton
+
+`useExportButton` provides a label for an export button for a resource. Props related to exporting bulk data from the resource will be provided by the [`useExport`](/docs/core/hooks/utilities/use-export) hook.
+
+```ts
+const {
+  label, // The label to be displayed on the button.
+} = useExportButton();
+```
+
+### useImportButton
+
+`useImportButton` provides a label for an import button for a resource. Props related to importing bulk data to the resource will be provided by the [`useImport`](/docs/core/hooks/utilities/use-import) hook.
+
+```ts
+const {
+  label, // The label to be displayed on the button.
+} = useImportButton();
+```

documentation/docs/routing/hooks/use-resource-params/index.md

@@ -0,0 +1,86 @@
+---
+title: useResourceParams
+source: packages/core/src/hooks/use-resource-params
+---
+
+`useResourceParams` is used to get the related parameters of the current resource such as `resource`, `id` and `action`. It also provides `formAction` to determine the action of the form and `setId` to set the `id` programmatically without having to use a separate state for it.
+
+## Usage
+
+```tsx
+const {
+  id?, // ID of the record
+  setId, // Function to set the ID
+  resource?, // Resource object
+  action?, // Passed action or inferred from the route
+  identifier?, // Identifier value of the resource
+  formAction?, // Form action derived from the action
+} = useResourceParams({
+  id?, // ID to set explicitly. Inferred from the route if not provided
+  action?, // Action to set explicitly. Inferred from the route if not provided
+  resource?, // Resource object to set explicitly. Inferred from the route if not provided
+});
+```
+
+### Inferring the `id` from the route
+
+When the `id` is not explicitly passed, it can be inferred from the route. Inference from the route is only possible under certain conditions:
+
+- If there's no explicitly set `resource` value.
+- If there's an explicitly set `resource` value and it's the same as the current route.
+
+This check is necessary to prevent the `id` from being inferred from a different resource.
+
+If there's no explicit `id` value, no `id` from the route or there's a mismatch between the `resource` and the route, the `id` will be set to `undefined`.
+
+### Inferring the `formAction` from the route
+
+The `formAction` is inferred from the `action` value.
+
+- If the `action` is a valid form action (`create`, `edit` or `clone`), the `formAction` will be set to the `action`.
+- Otherwise, the `formAction` will be set to `create`.
+
+This is done to provide a more convenient way to determine the action of the form.
+
+## Return Values
+
+### resource
+
+The `resource` object.
+
+### identifier
+
+Identifier value for the current resource, this can either be the `identifier` property or the `name` property of the resource.
+
+### id
+
+`id` parameter to be used in the actions.
+
+### setId
+
+Function to set the `id` programmatically.
+
+### action
+
+Current action to be performed. This can be explicitly passed via the `action` parameter or inferred from the route.
+
+### formAction
+
+Apart from the `action` value, `formAction` can only be `create`, `edit` or `clone`. If the `action` is not one of these, `formAction` will be set to `create` for convenience.
+
+## API Reference
+
+### Properties
+
+<PropsTable module="@refinedev/core/useResourceParams"  />
+
+### Return value
+
+| Description | Type                                                                       |
+| ----------- | -------------------------------------------------------------------------- |
+| resource    | `IResourceItem` \| `undefined`                                             |
+| identifier  | `string` \| `undefined`                                                    |
+| id          | [`BaseKey` \| `undefined`](/docs/core/interface-references#basekey)        |
+| setId       | `(id: BaseKey) => void`                                                    |
+| action      | `undefined` \| `"list"` \| `"create"` \| `"edit"` \| `"show"` \| `"clone"` |
+| formAction  | `"create"` \| `"edit"` \| `"clone"`                                        |

documentation/docs/routing/hooks/use-resource/index.md

@@ -42,11 +42,15 @@ The `resource` object.
 
 Resource name of the `resource` object.
 
-### id
+### ~~id~~ <PropTag deprecated />
+
+> Use [`useResourceParams`](/docs/routing/hooks/use-resource-params) instead.
 
 `id` parameter of the current route.
 
-### action
+### ~~action~~ <PropTag deprecated />
+
+> Use [`useResourceParams`](/docs/routing/hooks/use-resource-params) instead.
 
 `action` from the current route if there is a match.
 

documentation/sidebars.js

@@ -227,6 +227,7 @@ module.exports = {
           collapsed: false,
           label: "Hooks",
           items: [
+            "routing/hooks/use-resource-params/index",
             "routing/hooks/use-resource/index",
             "routing/hooks/use-go/index",
             "routing/hooks/use-back/index",
@@ -441,6 +442,7 @@ module.exports = {
             "core/hooks/utilities/use-breadcrumb/index",
             "core/hooks/utilities/use-import/index",
             "core/hooks/utilities/use-export/index",
+            "core/hooks/utilities/buttons/index",
           ],
         },
       ],