[fields] Allow to explicitly define the reference date and improve its default value

docs/data/date-pickers/custom-field/PickerWithAutocompleteField.tsx

@@ -15,7 +15,12 @@ import {
 
 interface AutoCompleteFieldProps
   extends UseDateFieldProps<Dayjs>,
-    BaseSingleInputFieldProps<Dayjs | null, FieldSection, DateValidationError> {
+    BaseSingleInputFieldProps<
+      Dayjs | null,
+      Dayjs,
+      FieldSection,
+      DateValidationError
+    > {
   /**
    * @typescript-to-proptypes-ignore
    */

docs/data/date-pickers/custom-field/PickerWithBrowserField.tsx

@@ -76,6 +76,7 @@ interface BrowserMultiInputDateRangeFieldProps
   extends UseDateRangeFieldProps<Dayjs>,
     BaseMultiInputFieldProps<
       DateRange<Dayjs>,
+      Dayjs,
       RangeFieldSection,
       DateRangeValidationError
     > {}
@@ -161,7 +162,12 @@ function BrowserDateRangePicker(props: DateRangePickerProps<Dayjs>) {
 
 interface BrowserDateFieldProps
   extends UseDateFieldProps<Dayjs>,
-    BaseSingleInputFieldProps<Dayjs | null, FieldSection, DateValidationError> {}
+    BaseSingleInputFieldProps<
+      Dayjs | null,
+      Dayjs,
+      FieldSection,
+      DateValidationError
+    > {}
 
 function BrowserDateField(props: BrowserDateFieldProps) {
   const { inputRef: externalInputRef, slots, slotProps, ...textFieldProps } = props;

docs/data/date-pickers/custom-field/PickerWithButtonField.tsx

@@ -14,7 +14,12 @@ import {
 
 interface ButtonFieldProps
   extends UseDateFieldProps<Dayjs>,
-    BaseSingleInputFieldProps<Dayjs | null, FieldSection, DateValidationError> {
+    BaseSingleInputFieldProps<
+      Dayjs | null,
+      Dayjs,
+      FieldSection,
+      DateValidationError
+    > {
   setOpen?: React.Dispatch<React.SetStateAction<boolean>>;
 }
 

docs/data/date-pickers/custom-field/PickerWithJoyField.tsx

@@ -125,6 +125,7 @@ interface JoyMultiInputDateRangeFieldProps
   extends UseDateRangeFieldProps<Dayjs>,
     BaseMultiInputFieldProps<
       DateRange<Dayjs>,
+      Dayjs,
       RangeFieldSection,
       DateRangeValidationError
     > {}
@@ -210,7 +211,12 @@ function JoyDateRangePicker(props: DateRangePickerProps<Dayjs>) {
 
 interface JoyDateFieldProps
   extends UseDateFieldProps<Dayjs>,
-    BaseSingleInputFieldProps<Dayjs | null, FieldSection, DateValidationError> {}
+    BaseSingleInputFieldProps<
+      Dayjs | null,
+      Dayjs,
+      FieldSection,
+      DateValidationError
+    > {}
 
 function JoyDateField(props: JoyDateFieldProps) {
   const { inputRef: externalInputRef, slots, slotProps, ...textFieldProps } = props;

docs/data/date-pickers/custom-field/custom-field.md

@@ -92,11 +92,21 @@ On the examples below, you can see that the typing of the props received by a cu
 ```tsx
 interface JoyDateFieldProps
   extends UseDateFieldProps<Dayjs>, // The headless field props
-    BaseSingleInputFieldProps<Dayjs | null, FieldSection, DateValidationError> {} // The DOM field props
+    BaseSingleInputFieldProps<
+      Dayjs | null,
+      Dayjs,
+      FieldSection,
+      DateValidationError
+    > {} // The DOM field props
 
 interface JoyDateTimeFieldProps
   extends UseDateTimeFieldProps<Dayjs>, // The headless field props
-    BaseSingleInputFieldProps<Dayjs | null, FieldSection, DateTimeValidationError> {} // The DOM field props
+    BaseSingleInputFieldProps<
+      Dayjs | null,
+      Dayjs,
+      FieldSection,
+      DateTimeValidationError
+    > {} // The DOM field props
 ```
 
 ### The headless field props

docs/pages/x/api/date-pickers/date-field.json

@@ -56,6 +56,10 @@
     "onError": { "type": { "name": "func" } },
     "onSelectedSectionsChange": { "type": { "name": "func" } },
     "readOnly": { "type": { "name": "bool" } },
+    "referenceDate": {
+      "type": { "name": "any" },
+      "default": "The closest valid date using the validation dates (do not use `shouldDisableDate & co) and the rounded to the most granular section used."
+    },
     "required": { "type": { "name": "bool" } },
     "selectedSections": {
       "type": {

docs/pages/x/api/date-pickers/date-time-field.json

@@ -63,6 +63,10 @@
     "onError": { "type": { "name": "func" } },
     "onSelectedSectionsChange": { "type": { "name": "func" } },
     "readOnly": { "type": { "name": "bool" } },
+    "referenceDate": {
+      "type": { "name": "any" },
+      "default": "The closest valid date using the validation dates (do not use `shouldDisableDate & co) and the rounded to the most granular section used."
+    },
     "required": { "type": { "name": "bool" } },
     "selectedSections": {
       "type": {

docs/pages/x/api/date-pickers/multi-input-date-range-field.json

@@ -35,6 +35,10 @@
     "onError": { "type": { "name": "func" } },
     "onSelectedSectionsChange": { "type": { "name": "func" } },
     "readOnly": { "type": { "name": "bool" } },
+    "referenceDate": {
+      "type": { "name": "any" },
+      "default": "The closest valid date using the validation dates (do not use `shouldDisableDate & co) and the rounded to the most granular section used."
+    },
     "selectedSections": {
       "type": {
         "name": "union",

docs/pages/x/api/date-pickers/multi-input-date-time-range-field.json

@@ -42,6 +42,10 @@
     "onError": { "type": { "name": "func" } },
     "onSelectedSectionsChange": { "type": { "name": "func" } },
     "readOnly": { "type": { "name": "bool" } },
+    "referenceDate": {
+      "type": { "name": "any" },
+      "default": "The closest valid date using the validation dates (do not use `shouldDisableDate & co) and the rounded to the most granular section used."
+    },
     "selectedSections": {
       "type": {
         "name": "union",

docs/pages/x/api/date-pickers/multi-input-time-range-field.json

@@ -38,6 +38,10 @@
     "onError": { "type": { "name": "func" } },
     "onSelectedSectionsChange": { "type": { "name": "func" } },
     "readOnly": { "type": { "name": "bool" } },
+    "referenceDate": {
+      "type": { "name": "any" },
+      "default": "The closest valid date using the validation dates (do not use `shouldDisableDate & co) and the rounded to the most granular section used."
+    },
     "selectedSections": {
       "type": {
         "name": "union",

docs/pages/x/api/date-pickers/single-input-date-range-field.json

@@ -56,6 +56,10 @@
     "onError": { "type": { "name": "func" } },
     "onSelectedSectionsChange": { "type": { "name": "func" } },
     "readOnly": { "type": { "name": "bool" } },
+    "referenceDate": {
+      "type": { "name": "any" },
+      "default": "The closest valid date using the validation dates (do not use `shouldDisableDate & co) and the rounded to the most granular section used."
+    },
     "required": { "type": { "name": "bool" } },
     "selectedSections": {
       "type": {

docs/pages/x/api/date-pickers/single-input-date-time-range-field.json

@@ -63,6 +63,10 @@
     "onError": { "type": { "name": "func" } },
     "onSelectedSectionsChange": { "type": { "name": "func" } },
     "readOnly": { "type": { "name": "bool" } },
+    "referenceDate": {
+      "type": { "name": "any" },
+      "default": "The closest valid date using the validation dates (do not use `shouldDisableDate & co) and the rounded to the most granular section used."
+    },
     "required": { "type": { "name": "bool" } },
     "selectedSections": {
       "type": {

docs/pages/x/api/date-pickers/single-input-time-range-field.json

@@ -59,6 +59,10 @@
     "onError": { "type": { "name": "func" } },
     "onSelectedSectionsChange": { "type": { "name": "func" } },
     "readOnly": { "type": { "name": "bool" } },
+    "referenceDate": {
+      "type": { "name": "any" },
+      "default": "The closest valid date using the validation dates (do not use `shouldDisableDate & co) and the rounded to the most granular section used."
+    },
     "required": { "type": { "name": "bool" } },
     "selectedSections": {
       "type": {

docs/pages/x/api/date-pickers/time-field.json

@@ -59,6 +59,10 @@
     "onError": { "type": { "name": "func" } },
     "onSelectedSectionsChange": { "type": { "name": "func" } },
     "readOnly": { "type": { "name": "bool" } },
+    "referenceDate": {
+      "type": { "name": "any" },
+      "default": "The closest valid date using the validation dates (do not use `shouldDisableDate & co) and the rounded to the most granular section used."
+    },
     "required": { "type": { "name": "bool" } },
     "selectedSections": {
       "type": {

docs/translations/api-docs/date-pickers/date-field.json

@@ -30,6 +30,7 @@
     "onError": "Callback fired when the error associated to the current value changes.<br><br><strong>Signature:</strong><br><code>function(error: TError, value: TValue) =&gt; void</code><br><em>error:</em> The new error.<br><em>value:</em> The value associated to the error.",
     "onSelectedSectionsChange": "Callback fired when the selected sections change.<br><br><strong>Signature:</strong><br><code>function(newValue: FieldSelectedSections) =&gt; void</code><br><em>newValue:</em> The new selected sections.",
     "readOnly": "It prevents the user from changing the value of the field (not from interacting with the field).",
+    "referenceDate": "The date to use to generate the part of the date-time not present in the format if not value / defaultValue is present. For example, on time fields it will be used to decide the date to set.",
     "required": "If <code>true</code>, the label is displayed as required and the <code>input</code> element is required.",
     "selectedSections": "The currently selected sections. This prop accept four formats: 1. If a number is provided, the section at this index will be selected. 2. If an object with a <code>startIndex</code> and <code>endIndex</code> properties are provided, the sections between those two indexes will be selected. 3. If a string of type <code>FieldSectionType</code> is provided, the first section with that name will be selected. 4. If <code>null</code> is provided, no section will be selected If not provided, the selected sections will be handled internally.",
     "shouldDisableDate": "Disable specific date.<br><br><strong>Signature:</strong><br><code>function(day: TDate) =&gt; boolean</code><br><em>day:</em> The date to test.<br> <em>returns</em> (boolean): If <code>true</code> the date will be disabled.",

docs/translations/api-docs/date-pickers/date-time-field.json

@@ -37,6 +37,7 @@
     "onError": "Callback fired when the error associated to the current value changes.<br><br><strong>Signature:</strong><br><code>function(error: TError, value: TValue) =&gt; void</code><br><em>error:</em> The new error.<br><em>value:</em> The value associated to the error.",
     "onSelectedSectionsChange": "Callback fired when the selected sections change.<br><br><strong>Signature:</strong><br><code>function(newValue: FieldSelectedSections) =&gt; void</code><br><em>newValue:</em> The new selected sections.",
     "readOnly": "It prevents the user from changing the value of the field (not from interacting with the field).",
+    "referenceDate": "The date to use to generate the part of the date-time not present in the format if not value / defaultValue is present. For example, on time fields it will be used to decide the date to set.",
     "required": "If <code>true</code>, the label is displayed as required and the <code>input</code> element is required.",
     "selectedSections": "The currently selected sections. This prop accept four formats: 1. If a number is provided, the section at this index will be selected. 2. If an object with a <code>startIndex</code> and <code>endIndex</code> properties are provided, the sections between those two indexes will be selected. 3. If a string of type <code>FieldSectionType</code> is provided, the first section with that name will be selected. 4. If <code>null</code> is provided, no section will be selected If not provided, the selected sections will be handled internally.",
     "shouldDisableClock": "Disable specific clock time.<br><br><strong>Signature:</strong><br><code>function(clockValue: number, view: TimeView) =&gt; boolean</code><br><em>clockValue:</em> The value to check.<br><em>view:</em> The clock type of the timeValue.<br> <em>returns</em> (boolean): If <code>true</code> the time will be disabled.",

docs/translations/api-docs/date-pickers/multi-input-date-range-field.json

@@ -17,6 +17,7 @@
     "onError": "Callback fired when the error associated to the current value changes.<br><br><strong>Signature:</strong><br><code>function(error: TError, value: TValue) =&gt; void</code><br><em>error:</em> The new error.<br><em>value:</em> The value associated to the error.",
     "onSelectedSectionsChange": "Callback fired when the selected sections change.<br><br><strong>Signature:</strong><br><code>function(newValue: FieldSelectedSections) =&gt; void</code><br><em>newValue:</em> The new selected sections.",
     "readOnly": "It prevents the user from changing the value of the field (not from interacting with the field).",
+    "referenceDate": "The date to use to generate the part of the date-time not present in the format if not value / defaultValue is present. For example, on time fields it will be used to decide the date to set.",
     "selectedSections": "The currently selected sections. This prop accept four formats: 1. If a number is provided, the section at this index will be selected. 2. If an object with a <code>startIndex</code> and <code>endIndex</code> properties are provided, the sections between those two indexes will be selected. 3. If a string of type <code>FieldSectionType</code> is provided, the first section with that name will be selected. 4. If <code>null</code> is provided, no section will be selected If not provided, the selected sections will be handled internally.",
     "shouldDisableDate": "Disable specific date.<br><br><strong>Signature:</strong><br><code>function(day: TDate, position: string) =&gt; boolean</code><br><em>day:</em> The date to test.<br><em>position:</em> The date to test, &#39;start&#39; or &#39;end&#39;.<br> <em>returns</em> (boolean): Returns <code>true</code> if the date should be disabled.",
     "shouldRespectLeadingZeros": "If <code>true</code>, the format will respect the leading zeroes (e.g: on dayjs, the format <code>M/D/YYYY</code> will render <code>8/16/2018</code>) If <code>false</code>, the format will always add leading zeroes (e.g: on dayjs, the format <code>M/D/YYYY</code> will render <code>08/16/2018</code>)<br>Warning n°1: Luxon is not able to respect the leading zeroes when using macro tokens (e.g: &quot;DD&quot;), so <code>shouldRespectLeadingZeros={true}</code> might lead to inconsistencies when using <code>AdapterLuxon</code>.<br>Warning n°2: When <code>shouldRespectLeadingZeros={true}</code>, the field will add an invisible character on the sections containing a single digit to make sure <code>onChange</code> is fired. If you need to get the clean value from the input, you can remove this character using <code>input.value.replace(/\\u200e/g, &#39;&#39;)</code>.<br>Warning n°3: When used in strict mode, dayjs and moment require to respect the leading zeros. This mean that when using <code>shouldRespectLeadingZeros={false}</code>, if you retrieve the value directly from the input (not listening to <code>onChange</code>) and your format contains tokens without leading zeros, the value will not be parsed by your library.",

docs/translations/api-docs/date-pickers/multi-input-date-time-range-field.json

@@ -24,6 +24,7 @@
     "onError": "Callback fired when the error associated to the current value changes.<br><br><strong>Signature:</strong><br><code>function(error: TError, value: TValue) =&gt; void</code><br><em>error:</em> The new error.<br><em>value:</em> The value associated to the error.",
     "onSelectedSectionsChange": "Callback fired when the selected sections change.<br><br><strong>Signature:</strong><br><code>function(newValue: FieldSelectedSections) =&gt; void</code><br><em>newValue:</em> The new selected sections.",
     "readOnly": "It prevents the user from changing the value of the field (not from interacting with the field).",
+    "referenceDate": "The date to use to generate the part of the date-time not present in the format if not value / defaultValue is present. For example, on time fields it will be used to decide the date to set.",
     "selectedSections": "The currently selected sections. This prop accept four formats: 1. If a number is provided, the section at this index will be selected. 2. If an object with a <code>startIndex</code> and <code>endIndex</code> properties are provided, the sections between those two indexes will be selected. 3. If a string of type <code>FieldSectionType</code> is provided, the first section with that name will be selected. 4. If <code>null</code> is provided, no section will be selected If not provided, the selected sections will be handled internally.",
     "shouldDisableClock": "Disable specific clock time.<br><br><strong>Signature:</strong><br><code>function(clockValue: number, view: TimeView) =&gt; boolean</code><br><em>clockValue:</em> The value to check.<br><em>view:</em> The clock type of the timeValue.<br> <em>returns</em> (boolean): If <code>true</code> the time will be disabled.",
     "shouldDisableDate": "Disable specific date.<br><br><strong>Signature:</strong><br><code>function(day: TDate, position: string) =&gt; boolean</code><br><em>day:</em> The date to test.<br><em>position:</em> The date to test, &#39;start&#39; or &#39;end&#39;.<br> <em>returns</em> (boolean): Returns <code>true</code> if the date should be disabled.",

docs/translations/api-docs/date-pickers/multi-input-time-range-field.json

@@ -20,6 +20,7 @@
     "onError": "Callback fired when the error associated to the current value changes.<br><br><strong>Signature:</strong><br><code>function(error: TError, value: TValue) =&gt; void</code><br><em>error:</em> The new error.<br><em>value:</em> The value associated to the error.",
     "onSelectedSectionsChange": "Callback fired when the selected sections change.<br><br><strong>Signature:</strong><br><code>function(newValue: FieldSelectedSections) =&gt; void</code><br><em>newValue:</em> The new selected sections.",
     "readOnly": "It prevents the user from changing the value of the field (not from interacting with the field).",
+    "referenceDate": "The date to use to generate the part of the date-time not present in the format if not value / defaultValue is present. For example, on time fields it will be used to decide the date to set.",
     "selectedSections": "The currently selected sections. This prop accept four formats: 1. If a number is provided, the section at this index will be selected. 2. If an object with a <code>startIndex</code> and <code>endIndex</code> properties are provided, the sections between those two indexes will be selected. 3. If a string of type <code>FieldSectionType</code> is provided, the first section with that name will be selected. 4. If <code>null</code> is provided, no section will be selected If not provided, the selected sections will be handled internally.",
     "shouldDisableClock": "Disable specific clock time.<br><br><strong>Signature:</strong><br><code>function(clockValue: number, view: TimeView) =&gt; boolean</code><br><em>clockValue:</em> The value to check.<br><em>view:</em> The clock type of the timeValue.<br> <em>returns</em> (boolean): If <code>true</code> the time will be disabled.",
     "shouldDisableTime": "Disable specific time.<br><br><strong>Signature:</strong><br><code>function(value: TDate, view: TimeView) =&gt; boolean</code><br><em>value:</em> The value to check.<br><em>view:</em> The clock type of the timeValue.<br> <em>returns</em> (boolean): If <code>true</code> the time will be disabled.",

docs/translations/api-docs/date-pickers/single-input-date-range-field.json

@@ -30,6 +30,7 @@
     "onError": "Callback fired when the error associated to the current value changes.<br><br><strong>Signature:</strong><br><code>function(error: TError, value: TValue) =&gt; void</code><br><em>error:</em> The new error.<br><em>value:</em> The value associated to the error.",
     "onSelectedSectionsChange": "Callback fired when the selected sections change.<br><br><strong>Signature:</strong><br><code>function(newValue: FieldSelectedSections) =&gt; void</code><br><em>newValue:</em> The new selected sections.",
     "readOnly": "It prevents the user from changing the value of the field (not from interacting with the field).",
+    "referenceDate": "The date to use to generate the part of the date-time not present in the format if not value / defaultValue is present. For example, on time fields it will be used to decide the date to set.",
     "required": "If <code>true</code>, the label is displayed as required and the <code>input</code> element is required.",
     "selectedSections": "The currently selected sections. This prop accept four formats: 1. If a number is provided, the section at this index will be selected. 2. If an object with a <code>startIndex</code> and <code>endIndex</code> properties are provided, the sections between those two indexes will be selected. 3. If a string of type <code>FieldSectionType</code> is provided, the first section with that name will be selected. 4. If <code>null</code> is provided, no section will be selected If not provided, the selected sections will be handled internally.",
     "shouldDisableDate": "Disable specific date.<br><br><strong>Signature:</strong><br><code>function(day: TDate, position: string) =&gt; boolean</code><br><em>day:</em> The date to test.<br><em>position:</em> The date to test, &#39;start&#39; or &#39;end&#39;.<br> <em>returns</em> (boolean): Returns <code>true</code> if the date should be disabled.",