Document SortButton and GenericButton

marmelab · Feb 13, 2021 · 882e5d9 · 882e5d9
1 parent 0891867
commit 882e5d9
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 13 deletions.
diff --git a/docs/Buttons.md b/docs/Buttons.md
@@ -247,8 +247,38 @@ export const PostList = (props) => (
 | `undoable`   | Optional | `boolean`       | true               | Allow users to cancel the deletion  |
 
 ### `<FilterButton>`
+
+This button is an internal component used by react-admin in [the `<Filter>` button/form combo](./List.md#the-filter-buttonform-combo).
+
+![List Filters](./img/list_filter.gif)
+
 ### `<SortButton>`
 
+Some List views don't have a natural UI for sorting - e.g. the `<SimpleList>`, or a list of images, don't have column headers like the `<Datagrid>`. For these cases, react-admin offers the `<SortButton>`, which displays a dropdown list of fields that the user can choose to sort on.
+
+![Sort Button](./img/sort-button.gif)
+
+`<SortButton>` expects one prop: `fields`, the list of fields it should allow to sort on. For instance, here is how to offer a button to sort on the `reference`, `sales`, and `stock` fields:
+
+```jsx
+import * as React from 'react';
+import { TopToolbar, SortButton, CreateButton, ExportButton } from 'react-admin';
+
+const ListActions = () => (
+    <TopToolbar>
+        <SortButton fields={['reference', 'sales', 'stock']} />
+        <CreateButton basePath="/products" />
+        <ExportButton />
+    </TopToolbar>
+);
+```
+
+| Prop         | Required | Type            | Default            | Description                         |
+| ------------ | -------- | --------------- | ------------------ | ----------------------------------- |
+| `fields`     | Required | `string[]`      | -                  | List of fields to offer sort on     |
+| `icon`       | Optional | `React.element` | `<DeleteIcon>`     | iconElement, e.g. `<CommentIcon />` |
+| `label`      | Optional | `string`        | 'ra.action.delete' | label or translation message to use |
+
 ## Record Buttons
 
 ### `<DeleteButton>`
@@ -259,17 +289,18 @@ export const PostList = (props) => (
 
 ### `<Button>`
 
-Responsive
+Base component for most react-admin buttons. Responsive (displays only the icon with a tooltip on mobile) and accessible.
 
-| Prop            | Required | Type                      | Default | Description           |
-| --------------- | -------- | ------------------------- | ------- | ------- |
-| `color`      | Optional | `string`                  | -       | path to link to, e.g. '/posts'                          |
-| `disabled`         | Optional | `string`                  | -       | path to link to, e.g. '/posts'                          |
-| `size`          | Optional | `React.element`           | -       | path to link to, e.g. '/posts'                          |
-| `alignIcon`          | Optional | `React.element`           | -       | path to link to, e.g. '/posts'                    |
-| `className`          | Optional | `React.element`           | -       | path to link to, e.g. '/posts'                    |
+| Prop         | Required | Type                           | Default | Description                              |
+| ------------ | -------- | ------------------------------ | ------- | ---------------------------------------- |
+| `alignIcon`  | Optional | `'left' | 'right`              | `'left'` | Icon position relative to the label     |
+| `children`   | Optional | `React.element`                | -        | icon to use                             |
+| `className`  | Optional | `string`                       | -        | path to link to, e.g. '/posts'          |
+| `color`      | Optional | `'default' | 'inherit'| 'primary' | 'secondary'` | `'primary'` | Label and icon color |
+| `disabled`   | Optional | `boolean`                      | `false`   | If `true`, the button will be disabled |
+| `size`       | Optional | `'large' | 'medium' | 'small'` | `'small'` | Button size                            |
 
-Other props are passed down to the underlying material-ui `<Button>`
+Other props are passed down to [the underlying material-ui `<Button>`](https://material-ui.com/api/button/).
 
 ### `<RefreshButton>`
 ### `<SkipNavigationButton>`

diff --git a/packages/ra-ui-materialui/src/button/SortButton.tsx b/packages/ra-ui-materialui/src/button/SortButton.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { FC, memo } from 'react';
+import { FC, ReactElement, memo } from 'react';
 import {
     Button,
     Menu,
@@ -39,9 +39,10 @@ import { useListSortContext, useTranslate } from 'ra-core';
  *     </TopToolbar>
  * );
  */
-const SortButton: FC<{ fields: string[]; label?: string }> = ({
+const SortButton: FC<SortButtonProps> = ({
     fields,
     label = 'ra.sort.sort_by',
+    icon = defaultIcon,
 }) => {
     const { resource, currentSort, setSort } = useListSortContext();
     const translate = useTranslate();
@@ -85,7 +86,7 @@ const SortButton: FC<{ fields: string[]; label?: string }> = ({
                         color="primary"
                         onClick={handleClick}
                     >
-                        <SortIcon />
+                        {icon}
                     </IconButton>
                 </Tooltip>
             ) : (
@@ -94,7 +95,7 @@ const SortButton: FC<{ fields: string[]; label?: string }> = ({
                     aria-haspopup="true"
                     color="primary"
                     onClick={handleClick}
-                    startIcon={<SortIcon />}
+                    startIcon={icon}
                     endIcon={<ArrowDropDownIcon />}
                     size="small"
                 >
@@ -129,9 +130,17 @@ const SortButton: FC<{ fields: string[]; label?: string }> = ({
     );
 };
 
+const defaultIcon = <SortIcon />;
+
 const inverseOrder = (sort: string) => (sort === 'ASC' ? 'DESC' : 'ASC');
 
 const arePropsEqual = (prevProps, nextProps) =>
     shallowEqual(prevProps.fields, nextProps.fields);
 
+export interface SortButtonProps {
+    fields: string[];
+    label?: string;
+    icon?: ReactElement;
+}
+
 export default memo(SortButton, arePropsEqual);