Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Refactor Pickers Localization documentation sections #11989

Merged
merged 15 commits into from
Feb 8, 2024
Merged

[docs] Refactor Pickers Localization documentation sections #11989

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
ca601f2
Fix typos
LukasTy Feb 8, 2024
022cc9f
Add missing `pages` word
LukasTy Feb 8, 2024
97c776d
Make `DateField` doc consistent and link to `custom formats`
LukasTy Feb 8, 2024
12742da
Move locaization before validation section for consistency
LukasTy Feb 8, 2024
4282441
Make `TimeField` doc consistent and link to `custom formats`
LukasTy Feb 8, 2024
e181882
Add missing localization sections to `clocks` pages
LukasTy Feb 8, 2024
8f8c5d0
Make `DateTimeField` doc consistent and link to `custom formats`
LukasTy Feb 8, 2024
fb4f604
Consistent localization section on date range components pages
LukasTy Feb 8, 2024
4167b1f
Consistent sections on `time-range-field`
LukasTy Feb 8, 2024
2c3716f
Consistent sections on `date-time-range` components
LukasTy Feb 8, 2024
89bc018
Consistent `Validation` section text
LukasTy Feb 8, 2024
5fbd094
Simplify `Localization` section copyright
LukasTy Feb 8, 2024
e66689f
docs:typescript:formatted
LukasTy Feb 8, 2024
7f57fac
Make `customize the format` section a sub-section of `Localization`
LukasTy Feb 8, 2024
563d387
Code review: Sam
LukasTy Feb 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/data/date-pickers/date-calendar/date-calendar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,10 +95,10 @@ The following demo shows how to add a badge on some day based on server side dat

{{"demo": "DateCalendarServerRequest.js"}}

## Validation
## Localization

You can find the documentation in the [Validation page](/x/react-date-pickers/validation/).
See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Localization
## Validation

You can find the documentation about localization in the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/).
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
8 changes: 2 additions & 6 deletions docs/data/date-pickers/date-field/CustomDateFormat.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,21 +6,17 @@ import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { DateField } from '@mui/x-date-pickers/DateField';

export default function CustomDateFormat() {
const [value, setValue] = React.useState(dayjs('2022-04-17'));

return (
<LocalizationProvider dateAdapter={AdapterDayjs}>
<DemoContainer components={['DateField', 'DateField']}>
<DateField
label="Dash separator"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17')}
format="MM-DD-YYYY"
/>
<DateField
label="Full letter month"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17')}
format="LL"
/>
</DemoContainer>
Expand Down
10 changes: 3 additions & 7 deletions docs/data/date-pickers/date-field/CustomDateFormat.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,22 @@
import * as React from 'react';
import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
import dayjs, { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { DateField } from '@mui/x-date-pickers/DateField';

export default function CustomDateFormat() {
const [value, setValue] = React.useState<Dayjs | null>(dayjs('2022-04-17'));

return (
<LocalizationProvider dateAdapter={AdapterDayjs}>
<DemoContainer components={['DateField', 'DateField']}>
<DateField
label="Dash separator"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17')}
format="MM-DD-YYYY"
/>
<DateField
label="Full letter month"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17')}
format="LL"
/>
</DemoContainer>
Expand Down
6 changes: 2 additions & 4 deletions docs/data/date-pickers/date-field/CustomDateFormat.tsx.preview
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
<DateField
label="Dash separator"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17')}
format="MM-DD-YYYY"
/>
<DateField
label="Full letter month"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17')}
format="LL"
/>
15 changes: 9 additions & 6 deletions docs/data/date-pickers/date-field/date-field.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,18 @@ The value of the component can be uncontrolled or controlled.
Learn more about the _Controlled and uncontrolled_ pattern in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
:::

## Customize the date format
## Localization

{{"demo": "CustomDateFormat.js"}}
See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Localization
### Customize the date format

Use the `LocalizationProvider` to change the date-library locale used in the time field.
See the [localization documentation page](/x/react-date-pickers/localization/) for more details.
{{"demo": "CustomDateFormat.js"}}

:::info
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMHO this demo should either not exist or be inside the "Localization" section below
THis would help people understand that the custom date format is part of the the Localization in our doc

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Initially, I was leaning towards that direction, but then I thought that the various custom formats for different components (date, time, and date-time) have lots of examples. If we want to provide at least a similar amount of demos in the Custom format section, it would be huge. 🤯
That's why I decided to keep the separate section. 🤔
WDYT?
Would moving those Customize the <x> format sections as sub-sections of Localization make more sense to you?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@flaviendelangle I've moved the Customize the format sections as subsections of Localization.
Let me know what you think. 😉

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can be a good trade-off 👌

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can be a great use-case for a switch like github does it on their webhook documentation:
Screenshot 2024-02-08 at 14 20 15

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the sense that you could provide a few options to select formats and then the fields will use that. WDYT?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a great suggestion, I'll explore that option. 👌

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@michelengelen I've explored that possibility but felt that the increased complexity and worse demo code readability didn't help. 🤔
If we wanted it to be useful, we'd need to have an elaborate demo with code preview. 🙈
I think that for starters this improvement should be useful enough. 🤞

See [Date format and localization—Custom formats](/x/react-date-pickers/adapters-locale/#custom-formats) for more details.
:::

## Validation

See the documentation page [validation documentation page](/x/react-date-pickers/validation/) for more details.
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
8 changes: 4 additions & 4 deletions docs/data/date-pickers/date-picker/date-picker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,13 +112,13 @@ You can enable the clearable behavior:

{{"demo": "ClearableProp.js"}}

## Validation
## Localization

You can find the documentation in the [Validation page](/x/react-date-pickers/validation/).
See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Localization
## Validation

You can find the documentation about localization in the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/).
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.

## Customization

Expand Down
8 changes: 4 additions & 4 deletions docs/data/date-pickers/date-range-calendar/date-range-calendar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,10 @@ You can take advantage of the [DateRangePickerDay](/x/api/date-pickers/date-rang

{{"demo": "CustomDateRangePickerDay.js"}}

## Validation
## Localization

You can find the documentation in the [Validation page](/x/react-date-pickers/validation/).
See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Localization
## Validation

You can find the documentation about localization in the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/).
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
8 changes: 8 additions & 0 deletions docs/data/date-pickers/date-range-field/date-range-field.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,11 @@ The value of the component can be uncontrolled or controlled.

Learn more about the _Controlled and uncontrolled_ pattern in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
:::

## Localization

See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Validation

See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
6 changes: 5 additions & 1 deletion docs/data/date-pickers/date-range-picker/date-range-picker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,9 +102,13 @@ To simplify range selection, you can add [shortcuts](/x/react-date-pickers/short

You can find the documentation in the [Custom field page](/x/react-date-pickers/custom-field/).

## Localization

See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Validation

You can find the documentation in the [Validation page](/x/react-date-pickers/validation/).
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.

## Month Range Picker 🚧

Expand Down
11 changes: 3 additions & 8 deletions docs/data/date-pickers/date-time-field/CustomDateTimeFormat.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,24 @@ import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { DateTimeField } from '@mui/x-date-pickers/DateTimeField';

export default function CustomDateTimeFormat() {
const [value, setValue] = React.useState(dayjs('2022-04-17T15:30'));

return (
<LocalizationProvider dateAdapter={AdapterDayjs}>
<DemoContainer
components={['DateTimeField', 'DateTimeField', 'DateTimeField']}
>
<DateTimeField
label="Format with meridiem"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17T15:30')}
format="L hh:mm a"
/>
<DateTimeField
label="Format without meridiem"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17T15:30')}
format="L HH:mm"
/>
<DateTimeField
label="Localized format with full letter month"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17T15:30')}
format="LLL"
/>
</DemoContainer>
Expand Down
13 changes: 4 additions & 9 deletions docs/data/date-pickers/date-time-field/CustomDateTimeFormat.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,29 @@
import * as React from 'react';
import dayjs, { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { DateTimeField } from '@mui/x-date-pickers/DateTimeField';

export default function CustomDateTimeFormat() {
const [value, setValue] = React.useState<Dayjs | null>(dayjs('2022-04-17T15:30'));

return (
<LocalizationProvider dateAdapter={AdapterDayjs}>
<DemoContainer
components={['DateTimeField', 'DateTimeField', 'DateTimeField']}
>
<DateTimeField
label="Format with meridiem"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17T15:30')}
format="L hh:mm a"
/>
<DateTimeField
label="Format without meridiem"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17T15:30')}
format="L HH:mm"
/>
<DateTimeField
label="Localized format with full letter month"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17T15:30')}
format="LLL"
/>
</DemoContainer>
Expand Down
15 changes: 15 additions & 0 deletions docs/data/date-pickers/date-time-field/CustomDateTimeFormat.tsx.preview
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<DateTimeField
label="Format with meridiem"
defaultValue={dayjs('2022-04-17T15:30')}
format="L hh:mm a"
/>
<DateTimeField
label="Format without meridiem"
defaultValue={dayjs('2022-04-17T15:30')}
format="L HH:mm"
/>
<DateTimeField
label="Localized format with full letter month"
defaultValue={dayjs('2022-04-17T15:30')}
format="LLL"
/>
15 changes: 9 additions & 6 deletions docs/data/date-pickers/date-time-field/date-time-field.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,18 @@ The value of the component can be uncontrolled or controlled.
Learn more about the _Controlled and uncontrolled_ pattern in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
:::

## Customize the date time format
## Localization

{{"demo": "CustomDateTimeFormat.js"}}
See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Localization
### Customize the date time format

Use the `LocalizationProvider` to change the date-library locale used in the date time field.
See the [localization documentation page](/x/react-date-pickers/localization/) for more details.
{{"demo": "CustomDateTimeFormat.js"}}

:::info
See [Date format and localization—Custom formats](/x/react-date-pickers/adapters-locale/#custom-formats) for more details.
:::

## Validation

See the documentation page [validation documentation page](/x/react-date-pickers/validation/) for more details.
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
8 changes: 4 additions & 4 deletions docs/data/date-pickers/date-time-picker/date-time-picker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,10 +110,10 @@ You might be interested in using the [Time Clock](/x/react-date-pickers/time-clo

{{"demo": "DateTimePickerViewRenderers.js"}}

## Validation
## Localization

You can find the documentation in the [Validation page](/x/react-date-pickers/validation/).
See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Localization
## Validation

You can find the documentation about localization in the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/).
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
8 changes: 8 additions & 0 deletions docs/data/date-pickers/date-time-range-field/date-time-range-field.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,11 @@ The value of the component can be uncontrolled or controlled.

Learn more about the _Controlled and uncontrolled_ pattern in the [React documentation](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
:::

## Localization

See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Validation

See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
6 changes: 5 additions & 1 deletion docs/data/date-pickers/date-time-range-picker/date-time-range-picker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,10 @@ You can pass a different view renderer to the Date Time Range Picker to customiz

{{"demo": "DateTimeRangePickerViewRenderer.js"}}

## Localization

See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Validation

You can find the documentation in the [Validation page](/x/react-date-pickers/validation/).
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
6 changes: 5 additions & 1 deletion docs/data/date-pickers/digital-clock/digital-clock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,10 @@ The following example combines these properties to customize which options are r

{{"demo": "DigitalClockSkipDisabled.js"}}

## Localization

See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Validation

You can find the documentation in the [Validation page](/x/react-date-pickers/validation/).
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
6 changes: 5 additions & 1 deletion docs/data/date-pickers/time-clock/time-clock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,10 @@ You can find more information about 12h/24h format in the [Date localization pag

{{"demo": "TimeClockAmPm.js"}}

## Localization

See the [Date format and localization](/x/react-date-pickers/adapters-locale/) and [Translated components](/x/react-date-pickers/localization/) documentation pages for more details.

## Validation

You can find the documentation in the [Validation page](/x/react-date-pickers/validation/).
See the [Validation](/x/react-date-pickers/validation/) documentation page for more details.
11 changes: 3 additions & 8 deletions docs/data/date-pickers/time-field/CustomTimeFormat.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,27 +6,22 @@ import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { TimeField } from '@mui/x-date-pickers/TimeField';

export default function CustomTimeFormat() {
const [value, setValue] = React.useState(dayjs('2022-04-17T15:30'));

return (
<LocalizationProvider dateAdapter={AdapterDayjs}>
<DemoContainer components={['TimeField', 'TimeField', 'TimeField']}>
<TimeField
label="Format with meridiem"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17T15:30')}
format="hh:mm a"
/>
<TimeField
label="Format without meridiem"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17T15:30')}
format="HH:mm"
/>
<TimeField
label="Format with seconds"
value={value}
onChange={(newValue) => setValue(newValue)}
defaultValue={dayjs('2022-04-17T15:30')}
format="HH:mm:ss"
/>
</DemoContainer>
Expand Down
Loading
Loading