Merge pull request #9439 from marmelab/singlefieldlist-empty

Update `<SingleFieldList>` to make it more powerful
marmelab · Nov 14, 2023 · 9768ee1 · 9768ee1
2 parents 9a3c3c8 + b5f8b66
commit 9768ee1
Show file tree

Hide file tree

Showing 12 changed files with 415 additions and 140 deletions.
diff --git a/docs/SingleFieldList.md b/docs/SingleFieldList.md
@@ -13,15 +13,32 @@ Use `<SingleFieldList>` when you want to display only one property for each reco
 
 ## Usage
 
-Use `<SingleFieldList>` wherever there is a `ListContext`. It is especially useful as child of `<ReferenceManyField>` and `<ReferenceArrayField>` components. `<SingleFieldList>` expects a single `<Field>` as child.
+`<SingleFieldList>` grabs the current `ListContext`, and renders a Material UI `<Stack>` with one `<ChipField>` for each record in the list, using the `recordRepresentation`. It is especially useful as child of `<ReferenceManyField>` and `<ReferenceArrayField>` components.
+
+Here is an example of a Post show page showing the list of tags for the current post:
 
 ```jsx
-<SingleFieldList>
-    <ChipField source="name" />
-</SingleFieldList>
+import {
+    Show,
+    SimpleShowLayout,
+    TextField,
+    ReferenceArrayField,
+    SingleFieldList
+} from 'react-admin';
+
+const PostShow = () => (
+    <Show>
+        <SimpleShowLayout>
+            <TextField source="title" />
+            <ReferenceArrayField label="Tags" reference="tags" source="tags">
+                <SingleFieldList />
+            </ReferenceArrayField>
+        </SimpleShowLayout>
+    </Show>
+);
 ```
 
-The following example shows how to use `<SingleFieldList>` to display a list of tags for each post in a Datagrid:
+You can also use  `<SingleFieldList>` in a list view, e.g. to display the tags for each post in a `<Datagrid>`:
 
 ```jsx
 import { 
@@ -45,9 +62,7 @@ const PostList = () => (
             <BooleanField source="commentable" />
             <NumberField source="views" />
             <ReferenceArrayField label="Tags" reference="tags" source="tags">
-                <SingleFieldList>
-                    <ChipField source="name" />
-                </SingleFieldList>
+                <SingleFieldList />
             </ReferenceArrayField>
         </Datagrid>
     </List>
@@ -56,14 +71,46 @@ const PostList = () => (
 
 ![SingleFieldList in Datagrid](./img/singlefieldlist-datagrid.png)
 
+You can customize how each record is displayed by passing a Field component as child. For example, you can change the field name used by the `<ChipField>`:
+
+```jsx
+<SingleFieldList>
+    <ChipField source="tag" clickable />
+</SingleFieldList>
+```
+
 ## Props
 
 `<SingleFieldList>` accepts the following props:
 
-| Prop        | Required | Type                      | Default | Description                                   |
-| ----------- | -------- | ------------------------- | ------- | --------------------------------------------- |
-| `linkType`  | Optional | `'edit' | 'show' | false` | `edit`  | The target of the link on each item           |
-| `sx`        | Optional | `object`                  |         | The sx props of the Material UI Box component |
+| Prop        | Required | Type                      | Default | Description                                     |
+| ----------- | -------- | ------------------------- | ------- | ----------------------------------------------- |
+| `children`  | Optional | `ReactNode`               |         | React element to render for each record         |
+| `empty`     | Optional | `ReactNode`               |         | React element to display when the list is empty |
+| `linkType`  | Optional | `'edit' | 'show' | false` | `edit`  | The target of the link on each item             |
+| `sx`        | Optional | `object`                  |         | The sx props of the Material UI Box component   |
+
+Additional props are passed down to the underlying [Material UI `<Stack>` component](https://mui.com/material-ui/react-stack/).
+
+## `children`
+
+By default, `<SingleFieldList>` renders a `<ChipField>` for each record. You can customize the rendering by passing a Field component as child. 
+
+For example, if you want to customize the field name used by the `<ChipField>`:
+
+```jsx
+<SingleFieldList>
+    <ChipField source="tag" clickable />
+</SingleFieldList>
+```
+
+## `empty`
+
+When the list is empty, `<SingleFieldList>` displays nothing. You can customize this behavior by passing a React element as the `empty` prop. For example, to display a message:
+
+```jsx
+<SingleFieldList empty={<p>Nothing to display</p>} />
+```
 
 ## `linkType`
 
@@ -76,9 +123,7 @@ The `<SingleFieldList>` items link to the edition page by default. You can set t
     reference="tags"
     source="tags"
 >
-    <SingleFieldList linkType="show">
-        <ChipField source="name" />
-    </SingleFieldList>
+    <SingleFieldList linkType="show" />
 </ReferenceArrayField>
 ```
 

diff --git a/examples/crm/src/contacts/ContactList.tsx b/examples/crm/src/contacts/ContactList.tsx
@@ -88,7 +88,8 @@ const ContactListContent = () => {
                                             <TextField source="name" />
                                         </ReferenceField>{' '}
                                         {contact.nb_notes &&
-                                            `- ${contact.nb_notes} notes `}
+                                            `- ${contact.nb_notes} notes`}
+                                        &nbsp;&nbsp;
                                         <TagsList />
                                     </>
                                 }

diff --git a/examples/crm/src/contacts/TagsList.tsx b/examples/crm/src/contacts/TagsList.tsx
@@ -26,7 +26,7 @@ export const TagsList = () => (
         source="tags"
         reference="tags"
     >
-        <SingleFieldList linkType={false} component="span">
+        <SingleFieldList linkType={false}>
             <ColoredChipField source="name" variant="outlined" size="small" />
         </SingleFieldList>
     </ReferenceArrayField>

diff --git a/examples/simple/src/posts/PostList.tsx b/examples/simple/src/posts/PostList.tsx
@@ -192,8 +192,8 @@ const PostListDesktop = () => (
                 cellClassName="hiddenOnSmallScreens"
                 headerClassName="hiddenOnSmallScreens"
             >
-                <SingleFieldList sx={{ my: -2 }}>
-                    <ChipField source="name.en" size="small" />
+                <SingleFieldList>
+                    <ChipField clickable source="name.en" size="small" />
                 </SingleFieldList>
             </ReferenceArrayField>
             <NumberField source="average_note" />

diff --git a/examples/simple/src/posts/PostShow.tsx b/examples/simple/src/posts/PostShow.tsx
@@ -75,6 +75,7 @@ const PostShow = () => {
                                 <ChipField
                                     source={`name.${locale}`}
                                     size="small"
+                                    clickable
                                 />
                             </SingleFieldList>
                         </ReferenceArrayField>

diff --git a/packages/ra-ui-materialui/src/field/ChipField.tsx b/packages/ra-ui-materialui/src/field/ChipField.tsx
@@ -71,5 +71,5 @@ const StyledChip = styled(Chip, {
     name: PREFIX,
     overridesResolver: (props, styles) => styles.root,
 })({
-    [`&.${ChipFieldClasses.chip}`]: { margin: 4, cursor: 'inherit' },
+    [`&.${ChipFieldClasses.chip}`]: { cursor: 'inherit' },
 });
diff --git a/packages/ra-ui-materialui/src/field/ReferenceArrayField.stories.tsx b/packages/ra-ui-materialui/src/field/ReferenceArrayField.stories.tsx
@@ -1,48 +1,102 @@
 import * as React from 'react';
 import fakeRestProvider from 'ra-data-fakerest';
+import { CardContent } from '@mui/material';
+import { ResourceDefinitionContextProvider } from 'ra-core';
 
 import { AdminContext } from '../AdminContext';
 import { Datagrid } from '../list';
 import { ReferenceArrayField } from './ReferenceArrayField';
 import { TextField } from './TextField';
-import { Show } from '../detail';
-import { CardContent } from '@mui/material';
+import { Show, SimpleShowLayout } from '../detail';
+
+export default { title: 'ra-ui-materialui/fields/ReferenceArrayField' };
 
 const fakeData = {
-    bands: [{ id: 1, name: 'band_1', members: [1, '2', '3'] }],
+    bands: [{ id: 1, name: 'The Beatles', members: [1, 2, 3, 4] }],
     artists: [
-        { id: 1, name: 'artist_1' },
-        { id: 2, name: 'artist_2' },
-        { id: 3, name: 'artist_3' },
-        { id: 4, name: 'artist_4' },
+        { id: 1, name: 'John Lennon' },
+        { id: 2, name: 'Paul McCartney' },
+        { id: 3, name: 'Ringo Star' },
+        { id: 4, name: 'George Harrison' },
+        { id: 5, name: 'Mick Jagger' },
     ],
 };
-
-export default { title: 'ra-ui-materialui/fields/ReferenceArrayField' };
-
 const dataProvider = fakeRestProvider(fakeData, false);
 
-export const DifferentIdTypes = () => {
-    return (
-        <AdminContext dataProvider={dataProvider}>
-            <CardContent>
-                <Show resource="bands" id={1} sx={{ width: 600 }}>
-                    <TextField source="name" fullWidth />
-                    <ReferenceArrayField
-                        fullWidth
-                        source="members"
-                        reference="artists"
-                    >
+const resouceDefs = {
+    artists: {
+        name: 'artists',
+        hasList: true,
+        hasEdit: true,
+        hasShow: true,
+        hasCreate: true,
+        recordRepresentation: 'name',
+    },
+};
+export const Basic = () => (
+    <AdminContext dataProvider={dataProvider}>
+        <ResourceDefinitionContextProvider definitions={resouceDefs}>
+            <Show resource="bands" id={1} sx={{ width: 600 }}>
+                <SimpleShowLayout>
+                    <TextField source="name" />
+                    <ReferenceArrayField source="members" reference="artists" />
+                </SimpleShowLayout>
+            </Show>
+        </ResourceDefinitionContextProvider>
+    </AdminContext>
+);
+
+export const Children = () => (
+    <AdminContext dataProvider={dataProvider}>
+        <ResourceDefinitionContextProvider definitions={resouceDefs}>
+            <Show resource="bands" id={1} sx={{ width: 600 }}>
+                <SimpleShowLayout>
+                    <TextField source="name" />
+                    <ReferenceArrayField source="members" reference="artists">
                         <Datagrid bulkActionButtons={false}>
                             <TextField source="id" />
                             <TextField source="name" />
                         </Datagrid>
                     </ReferenceArrayField>
-                </Show>
-            </CardContent>
-        </AdminContext>
-    );
+                </SimpleShowLayout>
+            </Show>
+        </ResourceDefinitionContextProvider>
+    </AdminContext>
+);
+
+const fakeDataWidthDifferentIdTypes = {
+    bands: [{ id: 1, name: 'band_1', members: [1, '2', '3'] }],
+    artists: [
+        { id: 1, name: 'artist_1' },
+        { id: 2, name: 'artist_2' },
+        { id: 3, name: 'artist_3' },
+        { id: 4, name: 'artist_4' },
+    ],
 };
+const dataProviderWithDifferentIdTypes = fakeRestProvider(
+    fakeDataWidthDifferentIdTypes,
+    false
+);
+
+export const DifferentIdTypes = () => (
+    <AdminContext dataProvider={dataProviderWithDifferentIdTypes}>
+        <CardContent>
+            <Show resource="bands" id={1} sx={{ width: 600 }}>
+                <TextField source="name" fullWidth />
+                <ReferenceArrayField
+                    fullWidth
+                    source="members"
+                    reference="artists"
+                >
+                    <Datagrid bulkActionButtons={false}>
+                        <TextField source="id" />
+                        <TextField source="name" />
+                    </Datagrid>
+                </ReferenceArrayField>
+            </Show>
+        </CardContent>
+    </AdminContext>
+);
 
 const dataProviderWithLog = {
     ...dataProvider,

diff --git a/packages/ra-ui-materialui/src/field/ReferenceArrayField.tsx b/packages/ra-ui-materialui/src/field/ReferenceArrayField.tsx
@@ -10,17 +10,15 @@ import {
     FilterPayload,
     ResourceContextProvider,
     useRecordContext,
-    useResourceDefinition,
     RaRecord,
 } from 'ra-core';
 import { styled } from '@mui/material/styles';
 import { SxProps } from '@mui/system';
+import { UseQueryOptions } from 'react-query';
 
 import { fieldPropTypes, FieldProps } from './types';
 import { LinearProgress } from '../layout';
 import { SingleFieldList } from '../list/SingleFieldList';
-import { ChipField } from './ChipField';
-import { UseQueryOptions } from 'react-query';
 
 /**
  * A container component that fetches records from another resource specified
@@ -152,27 +150,9 @@ export interface ReferenceArrayFieldViewProps
         Omit<ListControllerProps, 'queryOptions'> {}
 
 export const ReferenceArrayFieldView: FC<ReferenceArrayFieldViewProps> = props => {
-    const { children, pagination, reference, className, sx } = props;
+    const { children, pagination, className, sx } = props;
     const { isLoading, total } = useListContext(props);
 
-    const { recordRepresentation } = useResourceDefinition({
-        resource: reference,
-    });
-    let child = children ? (
-        children
-    ) : (
-        <SingleFieldList>
-            <ChipField
-                source={
-                    typeof recordRepresentation === 'string'
-                        ? recordRepresentation
-                        : 'id'
-                }
-                size="small"
-            />
-        </SingleFieldList>
-    );
-
     return (
         <Root className={className} sx={sx}>
             {isLoading ? (
@@ -181,7 +161,7 @@ export const ReferenceArrayFieldView: FC<ReferenceArrayFieldViewProps> = props =
                 />
             ) : (
                 <span>
-                    {child}
+                    {children || <SingleFieldList />}
                     {pagination && total !== undefined ? pagination : null}
                 </span>
             )}

diff --git a/packages/ra-ui-materialui/src/list/SimpleList/SimpleList.tsx b/packages/ra-ui-materialui/src/list/SimpleList/SimpleList.tsx
@@ -103,11 +103,6 @@ export const SimpleList = <RecordType extends RaRecord = any>(
         );
     }
 
-    /**
-     * Once loaded, the data for the list may be empty. Instead of
-     * displaying the table header with zero data rows,
-     * the SimpleList the empty component.
-     */
     if (data == null || data.length === 0 || total === 0) {
         if (empty) {
             return empty;