[pickers] Add proper support for UTC and timezones (#8261)

docs/data/date-pickers/adapters-locale/adapters-locale.md

@@ -250,74 +250,3 @@ This prop is available on all components that render a day calendar, including t
 The example below adds a dot at the end of each day in the calendar header:
 
 {{"demo": "CustomDayOfWeekFormat.js"}}
-
-## Use UTC dates
-
-### With dayjs
-
-To use UTC dates with `dayjs`, you have to:
-
-1. Extend `dayjs` with its `utc` plugin:
-
-   ```tsx
-   import dayjs from 'dayjs';
-   import utc from 'dayjs/plugin/utc';
-
-   dayjs.extend(utc);
-   ```
-
-2. Pass `dayjs.utc` to `LocalizationProvider` `dateLibInstance` prop:
-
-   ```tsx
-   <LocalizationProvider dateAdapter={AdapterDayjs} dateLibInstance={dayjs.utc}>
-     {children}
-   </LocalizationProvider>
-   ```
-
-3. Always pass dates created with `dayjs.utc`:
-
-   ```tsx
-   <DateTimePicker
-     // ✅ Valid props
-     value={dayjs.utc()}
-     minDate={dayjs.utc().startOf('month')}
-     // ❌ Invalid props
-     value={dayjs()}
-     minDate={dayjs().startOf('month')}
-   />
-   ```
-
-{{"demo": "UTCDayjs.js", "defaultCodeOpen": false}}
-
-### With moment
-
-To use UTC dates with `moment`, you have to:
-
-1. Pass `moment.utc` to `LocalizationProvider` `dateLibInstance` prop:
-
-   ```tsx
-   <LocalizationProvider dateAdapter={AdapterMoment} dateLibInstance={moment.utc}>
-     {children}
-   </LocalizationProvider>
-   ```
-
-2. Always pass dates created with `moment.utc`:
-
-   ```tsx
-   <DateTimePicker
-     // ✅ Valid props
-     value={moment.utc()}
-     minDate={moment.utc().startOf('month')}
-     // ❌ Invalid props
-     value={moment()}
-     minDate={moment().startOf('month')}
-   />
-   ```
-
-{{"demo": "UTCMoment.js", "defaultCodeOpen": false}}
-
-### Other libraries
-
-UTC support is an ongoing topic.
-
-We will update the documentation with examples using other date libraries once the support for them will be sufficient.

docs/data/date-pickers/timezone/BasicTimezoneProp.js

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { TimePicker } from '@mui/x-date-pickers/TimePicker';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+export default function BasicTimezoneProp() {
+  const [value, setValue] = React.useState(dayjs.utc('2022-04-17T15:30'));
+
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <Stack spacing={2}>
+        <TimePicker
+          value={value}
+          onChange={setValue}
+          timezone="America/New_York"
+          label={'Rendered in "America/New_York"'}
+        />
+        <TimePicker
+          value={value}
+          onChange={setValue}
+          timezone="Europe/Paris"
+          label={'Rendered in "Europe/Paris"'}
+        />
+        <Typography>
+          Stored value: {value == null ? 'null' : value.format()}
+        </Typography>
+      </Stack>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/timezone/BasicTimezoneProp.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import dayjs, { Dayjs } from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { TimePicker } from '@mui/x-date-pickers/TimePicker';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+export default function BasicTimezoneProp() {
+  const [value, setValue] = React.useState<Dayjs | null>(
+    dayjs.utc('2022-04-17T15:30'),
+  );
+
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <Stack spacing={2}>
+        <TimePicker
+          value={value}
+          onChange={setValue}
+          timezone="America/New_York"
+          label={'Rendered in "America/New_York"'}
+        />
+        <TimePicker
+          value={value}
+          onChange={setValue}
+          timezone="Europe/Paris"
+          label={'Rendered in "Europe/Paris"'}
+        />
+        <Typography>
+          Stored value: {value == null ? 'null' : value.format()}
+        </Typography>
+      </Stack>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/timezone/BasicTimezoneProp.tsx.preview

@@ -0,0 +1,15 @@
+<TimePicker
+  value={value}
+  onChange={setValue}
+  timezone="America/New_York"
+  label={'Rendered in "America/New_York"'}
+/>
+<TimePicker
+  value={value}
+  onChange={setValue}
+  timezone="Europe/Paris"
+  label={'Rendered in "Europe/Paris"'}
+/>
+<Typography>
+  Stored value: {value == null ? 'null' : value.format()}
+</Typography>

docs/data/date-pickers/timezone/BasicValueProp.js

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { TimePicker } from '@mui/x-date-pickers/TimePicker';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+export default function BasicValueProp() {
+  const [value, setValue] = React.useState(
+    dayjs.tz('2022-04-17T15:30', 'America/New_York'),
+  );
+
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <Stack spacing={2}>
+        <TimePicker
+          label={'Value timezone: "America/New_York"'}
+          value={value}
+          onChange={setValue}
+        />
+        <Typography>
+          Stored value: {value == null ? 'null' : value.format()}
+        </Typography>
+      </Stack>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/timezone/BasicValueProp.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import dayjs, { Dayjs } from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { TimePicker } from '@mui/x-date-pickers/TimePicker';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+export default function BasicValueProp() {
+  const [value, setValue] = React.useState<Dayjs | null>(
+    dayjs.tz('2022-04-17T15:30', 'America/New_York'),
+  );
+
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <Stack spacing={2}>
+        <TimePicker
+          label={'Value timezone: "America/New_York"'}
+          value={value}
+          onChange={setValue}
+        />
+        <Typography>
+          Stored value: {value == null ? 'null' : value.format()}
+        </Typography>
+      </Stack>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/timezone/BasicValueProp.tsx.preview

@@ -0,0 +1,8 @@
+<TimePicker
+  label={'Value timezone: "America/New_York"'}
+  value={value}
+  onChange={setValue}
+/>
+<Typography>
+  Stored value: {value == null ? 'null' : value.format()}
+</Typography>

docs/data/date-pickers/timezone/DayjsTimezone.js

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { DateTimePicker } from '@mui/x-date-pickers/DateTimePicker';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+export default function DayjsTimezone() {
+  const [value, setValue] = React.useState(
+    dayjs.tz('2022-04-17T15:30', 'America/New_York'),
+  );
+
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <Stack spacing={2}>
+        <DateTimePicker value={value} onChange={setValue} />
+        <Typography>
+          Stored value: {value == null ? 'null' : value.format()}
+        </Typography>
+      </Stack>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/timezone/DayjsTimezone.tsx

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import dayjs, { Dayjs } from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { DateTimePicker } from '@mui/x-date-pickers/DateTimePicker';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+export default function DayjsTimezone() {
+  const [value, setValue] = React.useState<Dayjs | null>(
+    dayjs.tz('2022-04-17T15:30', 'America/New_York'),
+  );
+
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <Stack spacing={2}>
+        <DateTimePicker value={value} onChange={setValue} />
+        <Typography>
+          Stored value: {value == null ? 'null' : value.format()}
+        </Typography>
+      </Stack>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/timezone/DayjsTimezone.tsx.preview

@@ -0,0 +1,4 @@
+<DateTimePicker value={value} onChange={setValue} />
+<Typography>
+  Stored value: {value == null ? 'null' : value.format()}
+</Typography>

docs/data/date-pickers/timezone/DayjsUTC.js

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { DateTimePicker } from '@mui/x-date-pickers/DateTimePicker';
+
+dayjs.extend(utc);
+
+export default function DayjsUTC() {
+  const [value, setValue] = React.useState(dayjs.utc('2022-04-17T15:30'));
+
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <Stack spacing={2}>
+        <DateTimePicker value={value} onChange={setValue} />
+        <Typography>
+          Stored value: {value == null ? 'null' : value.format()}
+        </Typography>
+      </Stack>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/timezone/DayjsUTC.tsx

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import dayjs, { Dayjs } from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { DateTimePicker } from '@mui/x-date-pickers/DateTimePicker';
+
+dayjs.extend(utc);
+
+export default function DayjsUTC() {
+  const [value, setValue] = React.useState<Dayjs | null>(
+    dayjs.utc('2022-04-17T15:30'),
+  );
+
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <Stack spacing={2}>
+        <DateTimePicker value={value} onChange={setValue} />
+        <Typography>
+          Stored value: {value == null ? 'null' : value.format()}
+        </Typography>
+      </Stack>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/timezone/DayjsUTC.tsx.preview

@@ -0,0 +1,4 @@
+<DateTimePicker value={value} onChange={setValue} />
+<Typography>
+  Stored value: {value == null ? 'null' : value.format()}
+</Typography>