[pickers] Use props.referenceDate timezone when props.value and `…

…props.defaultValue` are not defined (@flaviendelangle) (#15544)

Co-authored-by: Flavien DELANGLE <[email protected]>

packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.tsx

@@ -208,13 +208,14 @@ const DateRangeCalendar = React.forwardRef(function DateRangeCalendar<
   } = props;
 
   const { value, handleValueChange, timezone } = useControlledValueWithTimezone<
-    TDate,
     DateRange<TDate>,
+    TDate,
     NonNullable<typeof onChange>
   >({
     name: 'DateRangeCalendar',
     timezone: timezoneProp,
     value: valueProp,
+    referenceDate,
     defaultValue,
     onChange,
     valueManager: rangeValueManager,

packages/x-date-pickers-pro/src/internals/hooks/useMultiInputRangeField/useMultiInputDateRangeField.ts

@@ -47,6 +47,7 @@ export const useMultiInputDateRangeField = <
   const {
     value: valueProp,
     defaultValue,
+    referenceDate,
     format,
     formatDensity,
     shouldRespectLeadingZeros,
@@ -65,6 +66,7 @@ export const useMultiInputDateRangeField = <
     timezone: timezoneProp,
     value: valueProp,
     defaultValue,
+    referenceDate,
     onChange,
     valueManager: rangeValueManager,
   });

packages/x-date-pickers-pro/src/internals/hooks/useMultiInputRangeField/useMultiInputDateTimeRangeField.ts

@@ -47,6 +47,7 @@ export const useMultiInputDateTimeRangeField = <
   const {
     value: valueProp,
     defaultValue,
+    referenceDate,
     format,
     formatDensity,
     shouldRespectLeadingZeros,
@@ -65,6 +66,7 @@ export const useMultiInputDateTimeRangeField = <
     timezone: timezoneProp,
     value: valueProp,
     defaultValue,
+    referenceDate,
     onChange,
     valueManager: rangeValueManager,
   });

packages/x-date-pickers-pro/src/internals/hooks/useMultiInputRangeField/useMultiInputTimeRangeField.ts

@@ -47,6 +47,7 @@ export const useMultiInputTimeRangeField = <
   const {
     value: valueProp,
     defaultValue,
+    referenceDate,
     format,
     formatDensity,
     shouldRespectLeadingZeros,
@@ -67,6 +68,7 @@ export const useMultiInputTimeRangeField = <
     defaultValue,
     onChange,
     valueManager: rangeValueManager,
+    referenceDate,
   });
 
   const { validationError, getValidationErrorForNewValue } = useValidation({

packages/x-date-pickers/src/DateCalendar/DateCalendar.tsx

@@ -154,6 +154,7 @@ export const DateCalendar = React.forwardRef(function DateCalendar<TDate extends
     timezone: timezoneProp,
     value: valueProp,
     defaultValue,
+    referenceDate: referenceDateProp,
     onChange,
     valueManager: singleItemValueManager,
   });

packages/x-date-pickers/src/DigitalClock/DigitalClock.tsx

@@ -163,6 +163,7 @@ export const DigitalClock = React.forwardRef(function DigitalClock<TDate extends
     timezone: timezoneProp,
     value: valueProp,
     defaultValue,
+    referenceDate: referenceDateProp,
     onChange,
     valueManager: singleItemValueManager,
   });

packages/x-date-pickers/src/MonthCalendar/MonthCalendar.tsx

@@ -117,7 +117,8 @@ export const MonthCalendar = React.forwardRef(function MonthCalendar<TDate exten
     timezone: timezoneProp,
     value: valueProp,
     defaultValue,
-    onChange: onChange as (value: TDate | null) => void,
+    referenceDate: referenceDateProp,
+    onChange,
     valueManager: singleItemValueManager,
   });
 

packages/x-date-pickers/src/MultiSectionDigitalClock/MultiSectionDigitalClock.tsx

@@ -112,6 +112,7 @@ export const MultiSectionDigitalClock = React.forwardRef(function MultiSectionDi
     timezone: timezoneProp,
     value: valueProp,
     defaultValue,
+    referenceDate: referenceDateProp,
     onChange,
     valueManager: singleItemValueManager,
   });

packages/x-date-pickers/src/TimeClock/TimeClock.tsx

@@ -114,6 +114,7 @@ export const TimeClock = React.forwardRef(function TimeClock<TDate extends Picke
     timezone: timezoneProp,
     value: valueProp,
     defaultValue,
+    referenceDate: referenceDateProp,
     onChange,
     valueManager: singleItemValueManager,
   });

packages/x-date-pickers/src/YearCalendar/YearCalendar.tsx

@@ -126,7 +126,8 @@ export const YearCalendar = React.forwardRef(function YearCalendar<TDate extends
     timezone: timezoneProp,
     value: valueProp,
     defaultValue,
-    onChange: onChange as (value: TDate | null) => void,
+    referenceDate: referenceDateProp,
+    onChange,
     valueManager: singleItemValueManager,
   });
 

packages/x-date-pickers/src/internals/hooks/useField/useFieldState.ts

@@ -120,6 +120,7 @@ export const useFieldState = <
     timezone: timezoneProp,
     value: valueProp,
     defaultValue,
+    referenceDate: referenceDateProp,
     onChange,
     valueManager,
   });

packages/x-date-pickers/src/internals/hooks/usePicker/usePicker.types.ts

@@ -35,7 +35,7 @@ export interface UsePickerProps<
   TError,
   TExternalProps extends UsePickerViewsProps<TValue, TDate, TView, any, any>,
   TAdditionalProps extends {},
-> extends UsePickerValueProps<TValue, TError>,
+> extends UsePickerValueProps<TValue, TDate, TError>,
     UsePickerViewsProps<TValue, TDate, TView, TExternalProps, TAdditionalProps>,
     UsePickerLayoutProps {}
 

packages/x-date-pickers/src/internals/hooks/usePicker/usePickerValue.ts

@@ -154,7 +154,7 @@ export const usePickerValue = <
   TValue,
   TDate extends PickerValidDate,
   TSection extends FieldSection,
-  TExternalProps extends UsePickerValueProps<TValue, any>,
+  TExternalProps extends UsePickerValueProps<TValue, TDate, any>,
 >({
   props,
   valueManager,
@@ -175,6 +175,7 @@ export const usePickerValue = <
     defaultValue: inDefaultValue,
     closeOnSelect = wrapperVariant === 'desktop',
     timezone: timezoneProp,
+    referenceDate,
   } = props;
 
   const { current: defaultValue } = React.useRef(inDefaultValue);
@@ -225,6 +226,7 @@ export const usePickerValue = <
     timezone: timezoneProp,
     value: inValueWithoutRenderTimezone,
     defaultValue,
+    referenceDate,
     onChange,
     valueManager,
   });

packages/x-date-pickers/src/internals/hooks/usePicker/usePickerValue.types.ts

@@ -267,15 +267,18 @@ export interface UsePickerValueNonStaticProps {
 /**
  * Props used to handle the value of the pickers.
  */
-export interface UsePickerValueProps<TValue, TError>
+export interface UsePickerValueProps<TValue, TDate extends PickerValidDate, TError>
   extends UsePickerValueBaseProps<TValue, TError>,
     UsePickerValueNonStaticProps,
-    TimezoneProps {}
+    TimezoneProps {
+  // We don't add JSDoc here because we want the `referenceDate` JSDoc to be the one from the view which has more context.
+  referenceDate?: TDate;
+}
 
 export interface UsePickerValueParams<
   TValue,
   TDate extends PickerValidDate,
-  TExternalProps extends UsePickerValueProps<TValue, any>,
+  TExternalProps extends UsePickerValueProps<TValue, TDate, any>,
 > {
   props: TExternalProps;
   valueManager: PickerValueManager<TValue, TDate, InferError<TExternalProps>>;

packages/x-date-pickers/src/internals/hooks/useValueWithTimezone.test.tsx

@@ -0,0 +1,108 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { screen } from '@mui/internal-test-utils';
+import { PickersTimezone, PickerValidDate } from '@mui/x-date-pickers/models';
+import { createPickerRenderer } from 'test/utils/pickers';
+import { useValueWithTimezone } from './useValueWithTimezone';
+import { singleItemValueManager } from '../utils/valueManagers';
+
+describe('useValueWithTimezone', () => {
+  const { render, adapter } = createPickerRenderer({
+    clock: 'fake',
+    adapterName: 'luxon',
+  });
+
+  function runTest(params: {
+    timezone: PickersTimezone | undefined;
+    value: PickerValidDate | null | undefined;
+    defaultValue: PickerValidDate | null | undefined;
+    referenceDate: PickerValidDate | undefined;
+    expectedTimezone: PickersTimezone;
+  }) {
+    const { expectedTimezone, ...other } = params;
+
+    function TestComponent(props: typeof other) {
+      const { timezone } = useValueWithTimezone({
+        ...props,
+        valueManager: singleItemValueManager,
+        onChange: () => {},
+      });
+
+      return <div data-testid="result">{timezone}</div>;
+    }
+
+    render(<TestComponent {...other} />);
+
+    expect(screen.getByTestId('result').textContent).to.equal(expectedTimezone);
+  }
+
+  it('should use the timezone parameter when provided', () => {
+    runTest({
+      timezone: 'America/New_York',
+      value: undefined,
+      defaultValue: undefined,
+      referenceDate: undefined,
+      expectedTimezone: 'America/New_York',
+    });
+  });
+
+  it('should use the timezone parameter over the value parameter when both are provided', () => {
+    runTest({
+      timezone: 'America/New_York',
+      value: adapter.date(undefined, 'Europe/Paris'),
+      defaultValue: undefined,
+      referenceDate: undefined,
+      expectedTimezone: 'America/New_York',
+    });
+  });
+
+  it('should use the value parameter when provided', () => {
+    runTest({
+      timezone: undefined,
+      value: adapter.date(undefined, 'America/New_York'),
+      defaultValue: undefined,
+      referenceDate: undefined,
+      expectedTimezone: 'America/New_York',
+    });
+  });
+
+  it('should use the value parameter over the defaultValue parameter when both are provided', () => {
+    runTest({
+      timezone: undefined,
+      value: adapter.date(undefined, 'America/New_York'),
+      defaultValue: adapter.date(undefined, 'Europe/Paris'),
+      referenceDate: undefined,
+      expectedTimezone: 'America/New_York',
+    });
+  });
+
+  it('should use the defaultValue parameter when provided', () => {
+    runTest({
+      timezone: undefined,
+      value: undefined,
+      defaultValue: adapter.date(undefined, 'America/New_York'),
+      referenceDate: undefined,
+      expectedTimezone: 'America/New_York',
+    });
+  });
+
+  it('should use the referenceDate parameter when provided', () => {
+    runTest({
+      timezone: undefined,
+      value: undefined,
+      defaultValue: undefined,
+      referenceDate: adapter.date(undefined, 'America/New_York'),
+      expectedTimezone: 'America/New_York',
+    });
+  });
+
+  it('should use the "default" timezone is there is no way to deduce the user timezone', () => {
+    runTest({
+      timezone: undefined,
+      value: undefined,
+      defaultValue: undefined,
+      referenceDate: undefined,
+      expectedTimezone: 'default',
+    });
+  });
+});

packages/x-date-pickers/src/internals/hooks/useValueWithTimezone.ts

@@ -11,22 +11,17 @@ import { PickersTimezone, PickerValidDate } from '../../models';
  * - The value rendered is always the one from `props.timezone` if defined
  */
 export const useValueWithTimezone = <
-  TDate extends PickerValidDate,
   TValue,
+  TDate extends PickerValidDate,
   TChange extends (...params: any[]) => void,
 >({
   timezone: timezoneProp,
   value: valueProp,
   defaultValue,
+  referenceDate,
   onChange,
   valueManager,
-}: {
-  timezone: PickersTimezone | undefined;
-  value: TValue | undefined;
-  defaultValue: TValue | undefined;
-  onChange: TChange | undefined;
-  valueManager: PickerValueManager<TValue, TDate, any>;
-}) => {
+}: UseValueWithTimezoneParameters<TValue, TDate, TChange>) => {
   const utils = useUtils<TDate>();
 
   const firstDefaultValue = React.useRef(defaultValue);
@@ -45,7 +40,16 @@ export const useValueWithTimezone = <
     return valueManager.setTimezone(utils, inputTimezone, newValue);
   });
 
-  const timezoneToRender = timezoneProp ?? inputTimezone ?? 'default';
+  let timezoneToRender: PickersTimezone;
+  if (timezoneProp) {
+    timezoneToRender = timezoneProp;
+  } else if (inputTimezone) {
+    timezoneToRender = inputTimezone;
+  } else if (referenceDate) {
+    timezoneToRender = utils.getTimezone(referenceDate);
+  } else {
+    timezoneToRender = 'default';
+  }
 
   const valueWithTimezoneToRender = React.useMemo(
     () => valueManager.setTimezone(utils, timezoneToRender, inputValue),
@@ -64,24 +68,18 @@ export const useValueWithTimezone = <
  * Wrapper around `useControlled` and `useValueWithTimezone`
  */
 export const useControlledValueWithTimezone = <
-  TDate extends PickerValidDate,
   TValue,
+  TDate extends PickerValidDate,
   TChange extends (...params: any[]) => void,
 >({
   name,
   timezone: timezoneProp,
   value: valueProp,
   defaultValue,
+  referenceDate,
   onChange: onChangeProp,
   valueManager,
-}: {
-  name: string;
-  timezone: PickersTimezone | undefined;
-  value: TValue | undefined;
-  defaultValue: TValue | undefined;
-  onChange: TChange | undefined;
-  valueManager: PickerValueManager<TValue, TDate, any>;
-}) => {
+}: UseControlledValueWithTimezoneParameters<TValue, TDate, TChange>) => {
   const [valueWithInputTimezone, setValue] = useControlled({
     name,
     state: 'value',
@@ -98,7 +96,34 @@ export const useControlledValueWithTimezone = <
     timezone: timezoneProp,
     value: valueWithInputTimezone,
     defaultValue: undefined,
+    referenceDate,
     onChange,
     valueManager,
   });
 };
+
+interface UseValueWithTimezoneParameters<
+  TValue,
+  TDate extends PickerValidDate,
+  TChange extends (...params: any[]) => void,
+> {
+  timezone: PickersTimezone | undefined;
+  value: TValue | undefined;
+  defaultValue: TValue | undefined;
+  /**
+   * The reference date as passed to `props.referenceDate`.
+   * It does not need to have its default value.
+   * This is only used to determine the timezone to use when `props.value` and `props.defaultValue` are not defined.
+   */
+  referenceDate: TDate | undefined;
+  onChange: TChange | undefined;
+  valueManager: PickerValueManager<TValue, TDate, any>;
+}
+
+interface UseControlledValueWithTimezoneParameters<
+  TValue,
+  TDate extends PickerValidDate,
+  TChange extends (...params: any[]) => void,
+> extends UseValueWithTimezoneParameters<TValue, TDate, TChange> {
+  name: string;
+}