Merge pull request #9631 from marmelab/update-doc-for-MUI-X-date-time…

…-pickers [Documentation] Update docs for MUI X date/time pickers
marmelab · Feb 5, 2024 · 90c8386 · 90c8386
2 parents 6ffb08e + 85173af
commit 90c8386
Show file tree

Hide file tree

Showing 6 changed files with 234 additions and 1 deletion.
diff --git a/docs/DateInput.md b/docs/DateInput.md
@@ -16,6 +16,8 @@ Ideal for editing dates, `<DateInput>` renders an HTML `<input type="date">` ele
 
 The appearance of `<DateInput>` depends on the browser, and falls back to a text input on Safari. The date formatting in this input depends on the user's locale.
 
+React-admin also proposes a [DateInput styled with Material UI](#material-ui) documented at the end of this page.
+
 ## Usage
 
 ```jsx
@@ -53,3 +55,78 @@ If you need to render a UI despite the browser locale, MUI also proposes a [Date
   Your browser does not support the video tag.
 </video>
 
+## Material UI
+
+[React-admin Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> proposes an alternative `<DateInput>` styled with Material UI. 
+
+![DateInput with Material UI](./img/DateInput-MUI.png)
+
+This input also allows to specify the date format and the locale used. It is based on the [MUI X Date/Time pickers](https://mui.com/x/react-date-pickers/getting-started/).
+
+### Usage
+
+```tsx
+import { DateInput } from '@react-admin/ra-form-layout';
+import { Edit, SimpleForm } from 'react-admin';
+
+export const EventEdit = () => (
+    <Edit>
+        <SimpleForm>
+            <DateInput source="event_date" />
+        </SimpleForm>
+    </Edit>
+);
+```
+
+`<DateInput>` will accept either a `Date` object or any string that can be parsed into a `Date` as value. It will return a `Date` object, or `null` if the date is invalid.
+
+**Tip:** You can use the `parse` prop to change the format of the returned value. See [Parsing the date/time as an ISO string](#parsing-the-datetime-as-an-iso-string) for an example.
+
+### Props
+
+| Prop         | Required | Type              | Default                                | Description                                                                                                                                                                                  |
+| ------------ | -------- | ----------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fullWidth`  | -        | boolean           | `false`                                | If `true`, the input will expand to fill the form width                                                                                                                                      |
+| `helperText` | -        | string            | -                                      | Text to be displayed under the input                                                                                                                                                         |
+| `mask`       | -        | string            | -                                      | Alias for the MUI [`format`](https://mui.com/x/api/date-pickers/date-picker/#DatePicker-prop-format) prop. Format of the date/time when rendered in the input. Defaults to localized format. |
+| `parse`      | -        | Function          | `value => value === '' ? null : value` | Callback taking the input value, and returning the value you want stored in the form state.                                                                                                  |
+| `validate`   | -        | Function or Array | -                                      | Validation rules for the input. See the [Validation Documentation](https://marmelab.com/react-admin/Validation.html#per-input-validation-built-in-field-validators) for details.             |
+
+Except for the `format` prop (renamed `mask`), `<DateInput>` accepts the same props as the [MUI X Date/Time pickers](https://mui.com/x/api/date-pickers/). They also accept the common input props.
+
+### Providing your own `LocalizationProvider`
+
+MUI X Pickers need to be wrapped in a [LocalizationProvider](https://mui.com/components/pickers/#localization) to work properly. `<DateInput>` already includes a default `<LocalizationProvider>` using the `date-fns` adapter and the `enUS` locale.
+
+You can change the locale and the date format globally by wrapping the `<Admin>` with your own `<LocalizationProvider>`.
+
+Here is how to set up the pickers to use the `fr` locale:
+
+```tsx
+import { Admin, Resource } from 'react-admin';
+import { LocalizationProvider } from '@mui/x-date-pickers';
+import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
+import { fr } from 'date-fns/locale';
+import { EventEdit } from './events';
+
+export const App = () => (
+    <LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={fr}>
+        <Admin>
+            <Resource name="events" edit={EventEdit} />
+        </Admin>
+    </LocalizationProvider>
+);
+```
+
+**Note:** React Admin only supports the `date-fns` adapter for now.
+
+### Parsing the date/time as an ISO string
+
+By default, `<DateInput>` stores the date/time as a `Date` object in the form state. If you wish to store the date/time as an ISO string instead (or any other format), you can use the `parse` prop.
+
+```tsx
+<DateInput
+    source="published"
+    parse={(date: Date) => (date ? date.toISOString() : null)}
+/>
+```
diff --git a/docs/DateTimeInput.md b/docs/DateTimeInput.md
@@ -16,6 +16,8 @@ An input for editing dates with time. `<DateTimeInput>` renders an `<input type=
 
 The appearance depends on the browser, and falls back to a text input on safari. The date formatting in this input depends on the user's locale.
 
+React-admin also proposes a [DateTimeInput styled with Material UI](#material-ui) documented at the end of this page.
+
 ## Usage
 
 ```jsx
@@ -38,4 +40,80 @@ After modification by the user, the value is stored as a `Date` object, using th
 
 Internally, `<DateTimeInput>` renders an [`<input type="datetime-local">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local).
 
-If you need to implement your own `format` and `parse` functions, make sure the **format** function actually formats the input into [a valid local date and time string](https://developer.mozilla.org/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings).
+If you need to implement your own `format` and `parse` functions, make sure the **format** function actually formats the input into [a valid local date and time string](https://developer.mozilla.org/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings).
+
+## Material UI
+
+[React-admin Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> proposes an alternative `<DateTimeInput>` styled with Material UI. 
+
+![DateTimeInput with Material UI](./img/DateTimeInput-MUI.png)
+
+This input also allows to specify the date format and the locale used. It is based on the [MUI X Date/Time pickers](https://mui.com/x/react-date-pickers/getting-started/).
+
+### Usage
+
+```tsx
+import { DateTimeInput } from '@react-admin/ra-form-layout';
+import { Edit, SimpleForm } from 'react-admin';
+
+export const EventEdit = () => (
+    <Edit>
+        <SimpleForm>
+            <DateTimeInput source="event_date" />
+        </SimpleForm>
+    </Edit>
+);
+```
+
+`<DateTimeInput>` will accept either a `Date` object or any string that can be parsed into a `Date` as value. It will return a `Date` object, or `null` if the date is invalid.
+
+**Tip:** You can use the `parse` prop to change the format of the returned value. See [Parsing the date/time as an ISO string](#parsing-the-datetime-as-an-iso-string) for an example.
+
+### Props
+
+| Prop         | Required | Type              | Default                                | Description                                                                                                                                                                                  |
+| ------------ | -------- | ----------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fullWidth`  | -        | boolean           | `false`                                | If `true`, the input will expand to fill the form width                                                                                                                                      |
+| `helperText` | -        | string            | -                                      | Text to be displayed under the input                                                                                                                                                         |
+| `mask`       | -        | string            | -                                      | Alias for the MUI [`format`](https://mui.com/x/api/date-pickers/date-picker/#DatePicker-prop-format) prop. Format of the date/time when rendered in the input. Defaults to localized format. |
+| `parse`      | -        | Function          | `value => value === '' ? null : value` | Callback taking the input value, and returning the value you want stored in the form state.                                                                                                  |
+| `validate`   | -        | Function or Array | -                                      | Validation rules for the input. See the [Validation Documentation](https://marmelab.com/react-admin/Validation.html#per-input-validation-built-in-field-validators) for details.             |
+
+Except for the `format` prop (renamed `mask`), `<DateTimeInput> accepts the same props as the [MUI X Date/Time pickers](https://mui.com/x/api/date-pickers/). They also accept the common input props.
+
+### Providing your own `LocalizationProvider`
+
+MUI X Pickers need to be wrapped in a [LocalizationProvider](https://mui.com/components/pickers/#localization) to work properly. `<DateTimeInput>` already includes a default `<LocalizationProvider>` using the `date-fns` adapter and the `enUS` locale.
+
+You can change the locale and the date format globally by wrapping the `<Admin>` with your own `<LocalizationProvider>`.
+
+Here is how to set up the pickers to use the `fr` locale:
+
+```tsx
+import { Admin, Resource } from 'react-admin';
+import { LocalizationProvider } from '@mui/x-date-pickers';
+import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
+import { fr } from 'date-fns/locale';
+import { EventEdit } from './events';
+
+export const App = () => (
+    <LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={fr}>
+        <Admin>
+            <Resource name="events" edit={EventEdit} />
+        </Admin>
+    </LocalizationProvider>
+);
+```
+
+**Note:** React Admin only supports the `date-fns` adapter for now.
+
+### Parsing the date/time as an ISO string
+
+By default, `<DateTimeInput>` stores the date/time as a `Date` object in the form state. If you wish to store the date/time as an ISO string instead (or any other format), you can use the `parse` prop.
+
+```tsx
+<DateTimeInput
+    source="published"
+    parse={(date: Date) => (date ? date.toISOString() : null)}
+/>
+```
diff --git a/docs/TimeInput.md b/docs/TimeInput.md
@@ -37,6 +37,8 @@ An input for editing time. `<TimeInput>` renders a standard browser [Time Picker
 This component works with Date objects to handle the timezone using the browser locale.
 You can still pass string values as long as those can be converted to a JavaScript Date object.
 
+React-admin also proposes a [TimeInput styled with Material UI](#material-ui) documented at the end of this page.
+
 ## Usage
 
 ```jsx
@@ -51,3 +53,79 @@ import { TimeInput } from 'react-admin';
 
 `<TimeInput>` accepts the [common input props](./Inputs.md#common-input-props).
 
+
+## Material UI
+
+[React-admin Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> proposes an alternative `<TimeInput>` styled with Material UI. 
+
+![TimeInput with Material UI](./img/TimeInput-MUI.png)
+
+It allows for more customization of the UI than the default browser pickers. It also make it easier to work with specific locale and date formats.
+
+### Usage
+
+```tsx
+import { TimeInput } from '@react-admin/ra-form-layout';
+import { Edit, SimpleForm } from 'react-admin';
+
+export const EventEdit = () => (
+    <Edit>
+        <SimpleForm>
+            <TimeInput source="event_date" />
+        </SimpleForm>
+    </Edit>
+);
+```
+
+`<TimeInput>` will accept either a `Date` object or any string that can be parsed into a `Date` as value. It will return a `Date` object, or `null` if the date is invalid.
+
+**Tip:** You can use the `parse` prop to change the format of the returned value. See [Parsing the date/time as an ISO string](#parsing-the-datetime-as-an-iso-string) for an example.
+
+### Props
+
+| Prop         | Required | Type              | Default                                | Description                                                                                                                                                                                  |
+| ------------ | -------- | ----------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fullWidth`  | -        | boolean           | `false`                                | If `true`, the input will expand to fill the form width                                                                                                                                      |
+| `helperText` | -        | string            | -                                      | Text to be displayed under the input                                                                                                                                                         |
+| `mask`       | -        | string            | -                                      | Alias for the MUI [`format`](https://mui.com/x/api/date-pickers/date-picker/#DatePicker-prop-format) prop. Format of the date/time when rendered in the input. Defaults to localized format. |
+| `parse`      | -        | Function          | `value => value === '' ? null : value` | Callback taking the input value, and returning the value you want stored in the form state.                                                                                                  |
+| `validate`   | -        | Function or Array | -                                      | Validation rules for the input. See the [Validation Documentation](https://marmelab.com/react-admin/Validation.html#per-input-validation-built-in-field-validators) for details.             |
+
+Except for the `format` prop (renamed `mask`), `<TimeInput> accepts the same props as the [MUI X Date/Time pickers](https://mui.com/x/api/date-pickers/). They also accept the common input props.
+
+### Providing your own `LocalizationProvider`
+
+MUI X Pickers need to be wrapped in a [LocalizationProvider](https://mui.com/components/pickers/#localization) to work properly. `<TimeInput>` already includes a default `<LocalizationProvider>` using the `date-fns` adapter and the `enUS` locale.
+
+You can change the locale and the date format globally by wrapping the `<Admin>` with your own `<LocalizationProvider>`.
+
+Here is how to set up the pickers to use the `fr` locale:
+
+```tsx
+import { Admin, Resource } from 'react-admin';
+import { LocalizationProvider } from '@mui/x-date-pickers';
+import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
+import { fr } from 'date-fns/locale';
+import { EventEdit } from './events';
+
+export const App = () => (
+    <LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={fr}>
+        <Admin>
+            <Resource name="events" edit={EventEdit} />
+        </Admin>
+    </LocalizationProvider>
+);
+```
+
+**Note:** React Admin only supports the `date-fns` adapter for now.
+
+### Parsing the date/time as an ISO string
+
+By default, `<TimeInput>` stores the date/time as a `Date` object in the form state. If you wish to store the date/time as an ISO string instead (or any other format), you can use the `parse` prop.
+
+```tsx
+<TimeInput
+    source="published"
+    parse={(date: Date) => (date ? date.toISOString() : null)}
+/>
+```
diff --git a/docs/img/DateInput-MUI.png b/docs/img/DateInput-MUI.png
diff --git a/docs/img/DateTimeInput-MUI.png b/docs/img/DateTimeInput-MUI.png
diff --git a/docs/img/TimeInput-MUI.png b/docs/img/TimeInput-MUI.png