[RFR] Add invite to create the first record when the list is empty

docs/List.md

@@ -28,6 +28,7 @@ Here are all the props accepted by the `<List>` component:
 * [`filterDefaultValues`](#filter-default-values) (the default values for `alwaysOn` filters)
 * [`pagination`](#pagination)
 * [`aside`](#aside-component)
+* [`emptyState`](#empty-state)
 
 Here is the minimal code necessary to display a list of posts:
 
@@ -650,6 +651,7 @@ const PostList = props => (
     <List aside={<Aside />} {...props}>
         ...
     </List>
+);
 ```
 {% endraw %}
 
@@ -683,6 +685,34 @@ const Aside = ({ data, ids }) => (
 ```
 {% endraw %}
 
+### Empty state
+
+When there is no result, and there is no active filter, and the resource has a create page then a special page inviting the user to create the first record is displayed. Use the `emptyState` prop to modify that page, passing your custom component:
+
+{% raw %}
+```jsx
+import Button from '@material-ui/core/Button';
+import { CreateButton, List } from 'react-admin';
+
+const EmptyState = ({ basePath }) => (
+    <div style={{ textAlign: 'center', margin: '1em' }}>
+        <h1>No products available</h1>
+        <div>Create one or import from a file</div>
+        <CreateButton basePath={basePath} />
+        <Button onClick={...}>Import</Button>
+    </div>
+);
+
+const ProductList = props => (
+    <List emptyState={<EmptyState />} {...props}>
+        ...
+    </List>
+);
+```
+{% endraw %}
+
+The `emptyState` component receives the same props as the `aside` prop. Read the [section above](#aside-component) to check them. 
+
 ### CSS API
 
 The `List` component accepts the usual `className` prop but you can override many class names injected to the inner components by React-admin thanks to the `classes` property (as most Material UI components, see their [documentation about it](https://material-ui.com/customization/components/#overriding-styles-with-classes)). This property accepts the following keys:

packages/ra-language-english/index.js

@@ -39,6 +39,8 @@ module.exports = {
             loading: 'Loading',
             not_found: 'Not Found',
             show: '%{name} #%{id}',
+            empty: 'No %{name} yet.',
+            invite: 'Do you want to add one?',
         },
         input: {
             file: {

packages/ra-language-french/index.js

@@ -40,6 +40,8 @@ module.exports = {
             loading: 'Chargement',
             not_found: 'Page manquante',
             show: '%{name} #%{id}',
+            empty: 'Pas encore de %{name}.',
+            invite: 'Voulez-vous en créer un ?',
         },
         input: {
             file: {

packages/ra-ui-materialui/src/list/EmptyState.js

@@ -0,0 +1,48 @@
+import React from 'react';
+import Inbox from '@material-ui/icons/Inbox';
+import { makeStyles } from '@material-ui/styles';
+import { useTranslate } from 'ra-core';
+import { CreateButton } from '../button';
+import inflection from 'inflection';
+
+const useStyles = makeStyles({
+    message: {
+        textAlign: 'center',
+        fontFamily: 'Roboto, sans-serif',
+        opacity: 0.5,
+        margin: '0 1em',
+    },
+    icon: {
+        width: '9em',
+        height: '9em',
+    },
+    toolbar: {
+        textAlign: 'center',
+        marginTop: '2em',
+    },
+});
+
+const EmptyState = ({ resource, basePath }) => {
+    const classes = useStyles();
+    const translate = useTranslate();
+
+    const resourceName = translate(`resources.${resource}.name`, {
+        smart_count: 0,
+        _: inflection.humanize(resource),
+    }).toLowerCase();
+
+    return (
+        <>
+            <div className={classes.message}>
+                <Inbox className={classes.icon} />
+                <h1>{translate('ra.page.empty', { name: resourceName })}</h1>
+                <div>{translate('ra.page.invite')}</div>
+            </div>
+            <div className={classes.toolbar}>
+                <CreateButton variant="contained" basePath={basePath} />
+            </div>
+        </>
+    );
+};
+
+export default EmptyState;

packages/ra-ui-materialui/src/list/List.js

@@ -16,6 +16,7 @@ import DefaultPagination from './Pagination';
 import BulkDeleteButton from '../button/BulkDeleteButton';
 import BulkActionsToolbar from './BulkActionsToolbar';
 import DefaultActions from './ListActions';
+import EmptyState from './EmptyState';
 
 const DefaultBulkActionButtons = props => <BulkDeleteButton {...props} />;
 
@@ -100,6 +101,7 @@ const sanitizeRestProps = ({
     toggleItem,
     total,
     version,
+    emptyState,
     ...rest
 }) => rest;
 
@@ -117,20 +119,24 @@ export const ListView = props => {
         component: Content,
         exporter,
         title,
+        emptyState,
         ...rest
     } = props;
     useCheckMinimumRequiredProps('List', ['children'], props);
     const classes = useStyles({ classes: classesOverride });
-    const { defaultTitle, version } = rest;
+    const {
+        defaultTitle,
+        version,
+        total,
+        loaded,
+        loading,
+        hasCreate,
+        filterValues,
+    } = rest;
     const controllerProps = getListControllerProps(rest);
 
-    return (
-        <div
-            className={classnames('list-page', classes.root, className)}
-            {...sanitizeRestProps(rest)}
-        >
-            <Title title={title} defaultTitle={defaultTitle} />
-
+    const renderChildren = () => (
+        <>
             {(filters || actions) && (
                 <ListToolbar
                     filters={filters}
@@ -162,6 +168,25 @@ export const ListView = props => {
                 </Content>
                 {aside && cloneElement(aside, controllerProps)}
             </div>
+        </>
+    );
+
+    const shouldRenderEmptyState =
+        hasCreate &&
+        loaded &&
+        !loading &&
+        !total &&
+        !Object.keys(filterValues).length;
+
+    return (
+        <div
+            className={classnames('list-page', classes.root, className)}
+            {...sanitizeRestProps(rest)}
+        >
+            <Title title={title} defaultTitle={defaultTitle} />
+            {shouldRenderEmptyState
+                ? cloneElement(emptyState, controllerProps)
+                : renderChildren()}
         </div>
     );
 };
@@ -215,6 +240,7 @@ ListView.defaultProps = {
     component: Card,
     bulkActionButtons: <DefaultBulkActionButtons />,
     pagination: <DefaultPagination />,
+    emptyState: <EmptyState />,
 };
 
 /**

packages/ra-ui-materialui/src/list/List.spec.js

@@ -110,4 +110,34 @@ describe('<List />', () => {
         );
         expect(queryAllByText('Hello')).toHaveLength(1);
     });
+
+    it('should render an invite when the list is empty', () => {
+        const Dummy = () => <div />;
+        const { queryAllByText } = renderWithRedux(
+            <ThemeProvider theme={theme}>
+                <ListView {...defaultProps} total={0} hasCreate loaded>
+                    <Dummy />
+                </ListView>
+            </ThemeProvider>
+        );
+        expect(queryAllByText('ra.page.empty')).toHaveLength(1);
+    });
+
+    it('should not render an invite when a filter is active', () => {
+        const Dummy = () => <div />;
+        const { queryAllByText } = renderWithRedux(
+            <ThemeProvider theme={theme}>
+                <ListView
+                    {...defaultProps}
+                    filterValues={{ q: 'foo' }}
+                    total={0}
+                    hasCreate
+                    loaded
+                >
+                    <Dummy />
+                </ListView>
+            </ThemeProvider>
+        );
+        expect(queryAllByText('ra.page.empty')).toHaveLength(0);
+    });
 });