Add support for <ReferenceField emptyText> when the reference is missing

docs/ReferenceField.md

@@ -66,12 +66,28 @@ With this configuration, `<ReferenceField>` wraps the user's name in a link to t
 | `source`    | Required | `string`            | -        | Name of the property to display |
 | `reference` | Required | `string`            | -        | The name of the resource for the referenced records, e.g. 'posts' |
 | `children`  | Required | `ReactNode`         | -        | One or more Field elements used to render the referenced record |
+| `emptyText` | Optional | `string`            | ''       | Defines a text to be shown when the field has no value or when the reference is missing |
 | `label`     | Optional | `string | Function` | `resources.[resource].fields.[source]`   | Label to use for the field when rendered in layout components  |
 | `link`      | Optional | `string | Function` | `edit`   | Target of the link wrapping the rendered child. Set to `false` to disable the link. |
 | `sortBy`    | Optional | `string | Function` | `source` | Name of the field to use for sorting when used in a Datagrid |
 
 `<ReferenceField>` also accepts the [common field props](./Fields.md#common-field-props).
 
+## `empytText`
+
+`<ReferenceField>` can display a custom message when the referenced record is missing, thanks to the `emptyText` prop.
+
+```jsx
+<ReferenceField source="user_id" reference="users" emptyText="Missing user">
+    <TextField source="name" />
+</ReferenceField>
+```
+
+`<ReferenceField>` renders the `emptyText`:
+
+- when the referenced record is missing (no record in the `users` table with the right `user_id`), or
+- when the field is empty (no `user_id` in the record).
+
 ## `label`
 
 By default, `<SimpleShowLayout>`, `<Datagrid>` and other layout components infer the label of a field based on its `source`. For a `<ReferenceField>`, this may not be what you expect:

packages/ra-ui-materialui/src/field/ReferenceField.spec.tsx

@@ -11,7 +11,7 @@ import { QueryClient } from 'react-query';
 import { createTheme, ThemeProvider } from '@mui/material/styles';
 
 import { ReferenceField } from './ReferenceField';
-import { Children } from './ReferenceField.stories';
+import { Children, MissingReference } from './ReferenceField.stories';
 import { TextField } from './TextField';
 
 const theme = createTheme({});
@@ -243,6 +243,11 @@ describe('<ReferenceField />', () => {
         expect(screen.getByText('EMPTY')).not.toBeNull();
     });
 
+    it('should display the emptyText if there is no reference', async () => {
+        render(<MissingReference />);
+        await screen.findByText('no detail');
+    });
+
     it('should use record from RecordContext', async () => {
         const dataProvider = testDataProvider({
             getMany: jest.fn().mockResolvedValue({

packages/ra-ui-materialui/src/field/ReferenceField.stories.tsx

@@ -79,6 +79,25 @@ export const Empty = () => (
     </Wrapper>
 );
 
+const missingReferenceDataProvider = {
+    getMany: () =>
+        Promise.resolve({
+            data: [],
+        }),
+} as any;
+
+export const MissingReference = () => (
+    <Wrapper dataProvider={missingReferenceDataProvider}>
+        <ReferenceField
+            source="detail_id"
+            reference="book_details"
+            emptyText="no detail"
+        >
+            <TextField source="ISBN" />
+        </ReferenceField>
+    </Wrapper>
+);
+
 export const Link = () => (
     <Wrapper>
         <ReferenceField source="detail_id" reference="book_details" link="show">

packages/ra-ui-materialui/src/field/ReferenceField.tsx

@@ -77,7 +77,12 @@ export const ReferenceField: FC<ReferenceFieldProps> = props => {
             </Typography>
         ) : null
     ) : (
-        <NonEmptyReferenceField {...rest} record={record} id={id} />
+        <NonEmptyReferenceField
+            {...rest}
+            emptyText={emptyText}
+            record={record}
+            id={id}
+        />
     );
 };
 
@@ -123,7 +128,7 @@ export interface ReferenceFieldProps<RecordType extends RaRecord = any>
  * which cannot be called conditionally when get(record, source) is empty.
  */
 export const NonEmptyReferenceField: FC<
-    Omit<ReferenceFieldProps, 'emptyText' | 'source'> & { id: Identifier }
+    Omit<ReferenceFieldProps, 'source'> & { id: Identifier }
 > = ({ children, id, record, reference, link, ...props }) => {
     const createPath = useCreatePath();
     const resourceLinkPath =
@@ -162,6 +167,7 @@ export const ReferenceFieldView: FC<ReferenceFieldViewProps> = props => {
     const {
         children,
         className,
+        emptyText,
         error,
         isLoading,
         referenceRecord,
@@ -185,7 +191,7 @@ export const ReferenceFieldView: FC<ReferenceFieldViewProps> = props => {
         return <LinearProgress />;
     }
     if (!referenceRecord) {
-        return null;
+        return emptyText ? <>{emptyText}</> : null;
     }
 
     if (resourceLinkPath) {