[docs] New recipe of a read-only field

docs/data/date-pickers/experimentation/CustomField.js → docs/data/date-pickers/custom-field/custom-behavior/ReadOnlyMaterialTextField.js

@@ -1,47 +1,61 @@
 import * as React from 'react';
-import dayjs from 'dayjs';
+
 import TextField from '@mui/material/TextField';
-import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
 import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
 import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
 import { DatePicker } from '@mui/x-date-pickers/DatePicker';
 import { useValidation, validateDate } from '@mui/x-date-pickers/validation';
-import { useSplitFieldProps } from '@mui/x-date-pickers/hooks';
+import {
+  useSplitFieldProps,
+  useParsedFormat,
+  usePickersContext,
+} from '@mui/x-date-pickers/hooks';
 
-function ReadOnlyField(props) {
+function ReadOnlyDateField(props) {
   const { internalProps, forwardedProps } = useSplitFieldProps(props, 'date');
-
   const { value, timezone, format } = internalProps;
   const { InputProps, slotProps, slots, ...other } = forwardedProps;
 
+  const pickersContext = usePickersContext();
+
+  const parsedFormat = useParsedFormat(internalProps);
   const { hasValidationError } = useValidation({
     validator: validateDate,
     value,
     timezone,
     props: internalProps,
   });
 
+  const handleTogglePicker = (event) => {
+    if (pickersContext.open) {
+      pickersContext.onClose(event);
+    } else {
+      pickersContext.onOpen(event);
+    }
+  };
+
   return (
     <TextField
       {...other}
       value={value == null ? '' : value.format(format)}
+      placeholder={parsedFormat}
       InputProps={{ ...InputProps, readOnly: true }}
       error={hasValidationError}
+      onClick={handleTogglePicker}
     />
   );
 }
 
-export default function CustomField() {
+function ReadOnlyFieldDatePicker(props) {
+  return (
+    <DatePicker {...props} slots={{ ...props.slots, field: ReadOnlyDateField }} />
+  );
+}
+
+export default function ReadOnlyMaterialTextField() {
   return (
     <LocalizationProvider dateAdapter={AdapterDayjs}>
-      <DemoContainer components={['DatePicker']}>
-        <DatePicker
-          label="Date Picker"
-          slots={{ field: ReadOnlyField }}
-          maxDate={dayjs('2022-04-17')}
-          defaultValue={dayjs('2022-04-18')}
-        />
-      </DemoContainer>
+      <ReadOnlyFieldDatePicker />
     </LocalizationProvider>
   );
 }

docs/data/date-pickers/experimentation/CustomField.tsx → docs/data/date-pickers/custom-field/custom-behavior/ReadOnlyMaterialTextField.tsx

@@ -1,47 +1,65 @@
 import * as React from 'react';
-import dayjs, { Dayjs } from 'dayjs';
+import { Dayjs } from 'dayjs';
 import TextField from '@mui/material/TextField';
-import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
 import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
 import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
-import { DatePicker, DatePickerFieldProps } from '@mui/x-date-pickers/DatePicker';
+import {
+  DatePicker,
+  DatePickerProps,
+  DatePickerFieldProps,
+} from '@mui/x-date-pickers/DatePicker';
 import { useValidation, validateDate } from '@mui/x-date-pickers/validation';
-import { useSplitFieldProps } from '@mui/x-date-pickers/hooks';
+import {
+  useSplitFieldProps,
+  useParsedFormat,
+  usePickersContext,
+} from '@mui/x-date-pickers/hooks';
 
-function ReadOnlyField(props: DatePickerFieldProps<Dayjs, false>) {
+function ReadOnlyDateField(props: DatePickerFieldProps<Dayjs, false>) {
   const { internalProps, forwardedProps } = useSplitFieldProps(props, 'date');
-
   const { value, timezone, format } = internalProps;
   const { InputProps, slotProps, slots, ...other } = forwardedProps;
 
+  const pickersContext = usePickersContext();
+
+  const parsedFormat = useParsedFormat(internalProps);
   const { hasValidationError } = useValidation({
     validator: validateDate,
     value,
     timezone,
     props: internalProps,
   });
 
+  const handleTogglePicker = (event: React.UIEvent) => {
+    if (pickersContext.open) {
+      pickersContext.onClose(event);
+    } else {
+      pickersContext.onOpen(event);
+    }
+  };
+
   return (
     <TextField
       {...other}
       value={value == null ? '' : value.format(format)}
+      placeholder={parsedFormat}
       InputProps={{ ...InputProps, readOnly: true }}
       error={hasValidationError}
+      onClick={handleTogglePicker}
     />
   );
 }
 
-export default function CustomField() {
+function ReadOnlyFieldDatePicker(props: DatePickerProps<Dayjs>) {
+  return (
+    <DatePicker {...props} slots={{ ...props.slots, field: ReadOnlyDateField }} />
+  );
+}
+
+export default function ReadOnlyMaterialTextField() {
   return (
     <LocalizationProvider dateAdapter={AdapterDayjs}>
-      <DemoContainer components={['DatePicker']}>
-        <DatePicker
-          label="Date Picker"
-          slots={{ field: ReadOnlyField }}
-          maxDate={dayjs('2022-04-17')}
-          defaultValue={dayjs('2022-04-18')}
-        />
-      </DemoContainer>
+      <ReadOnlyFieldDatePicker />
     </LocalizationProvider>
   );
 }

docs/data/date-pickers/custom-field/custom-behavior/ReadOnlyMaterialTextField.tsx.preview

@@ -0,0 +1 @@
+<ReadOnlyFieldDatePicker />

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

@@ -158,10 +158,17 @@ you can replace the field with an `Autocomplete` listing those dates:
 
 {{"demo": "PickerWithAutocompleteField.js", "defaultCodeOpen": false}}
 
+### Using a read-only `TextField`
+
+If you want users to select a value exclusively through the views
+but you still want the UI to look like a `TextField`, you can replace the field with a read-only `TextField`:
+
+{{"demo": "custom-behavior/ReadOnlyMaterialTextField.js", "defaultCodeOpen": false}}
+
 ### Using a `Button`
 
-If you only want to allow the user to pick a value through the views,
-you can replace the field with a `Button`:
+If you want users to select a value exclusively through the views
+and you don't want the UI to look like a `TextField`, you can replace the field with a `Button`:
 
 {{"demo": "PickerWithButtonField.js", "defaultCodeOpen": false}}
 

docs/data/date-pickers/experimentation/experimentation.md

@@ -5,7 +5,3 @@ productId: x-date-pickers
 # Date and Time Pickers experimentation
 
 <p class="description">Demos not accessible through the navbar of the doc</p>
-
-## Custom field
-
-{{"demo": "CustomField.js"}}

packages/x-date-pickers-pro/src/internals/hooks/useDesktopRangePicker/useDesktopRangePicker.tsx

@@ -1,7 +1,6 @@
 import * as React from 'react';
 import useSlotProps from '@mui/utils/useSlotProps';
 import { useLicenseVerifier } from '@mui/x-license';
-import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
 import { PickersLayout, PickersLayoutSlotProps } from '@mui/x-date-pickers/PickersLayout';
 import {
   executeInTheNextEventLoopTick,
@@ -11,6 +10,7 @@ import {
   ExportedBaseToolbarProps,
   DateOrTimeViewWithMeridiem,
   ExportedBaseTabsProps,
+  PickersProvider,
 } from '@mui/x-date-pickers/internals';
 import { PickerValidDate, FieldRef, InferError } from '@mui/x-date-pickers/models';
 import {
@@ -93,6 +93,7 @@ export const useDesktopRangePicker = <
     renderCurrentView,
     shouldRestoreFocus,
     fieldProps: pickerFieldProps,
+    contextValue,
   } = usePicker<
     DateRange<TDate>,
     TDate,
@@ -209,7 +210,7 @@ export const useDesktopRangePicker = <
   const Layout = slots?.layout ?? PickersLayout;
 
   const renderPicker = () => (
-    <LocalizationProvider localeText={localeText}>
+    <PickersProvider contextValue={contextValue} localeText={localeText}>
       <Field {...enrichedFieldProps} />
       <PickersPopper
         role="tooltip"
@@ -233,7 +234,7 @@ export const useDesktopRangePicker = <
           {renderCurrentView()}
         </Layout>
       </PickersPopper>
-    </LocalizationProvider>
+    </PickersProvider>
   );
 
   return {

packages/x-date-pickers-pro/src/internals/hooks/useMobileRangePicker/useMobileRangePicker.tsx

@@ -1,14 +1,14 @@
 import * as React from 'react';
 import useSlotProps from '@mui/utils/useSlotProps';
 import { useLicenseVerifier } from '@mui/x-license';
-import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
 import { PickersLayout, PickersLayoutSlotProps } from '@mui/x-date-pickers/PickersLayout';
 import {
   usePicker,
   PickersModalDialog,
   ExportedBaseToolbarProps,
   DateOrTimeViewWithMeridiem,
   ExportedBaseTabsProps,
+  PickersProvider,
 } from '@mui/x-date-pickers/internals';
 import { usePickersTranslations } from '@mui/x-date-pickers/hooks';
 import { PickerValidDate, FieldRef, InferError } from '@mui/x-date-pickers/models';
@@ -88,6 +88,7 @@ export const useMobileRangePicker = <
     layoutProps,
     renderCurrentView,
     fieldProps: pickerFieldProps,
+    contextValue,
   } = usePicker<
     DateRange<TDate>,
     TDate,
@@ -214,7 +215,7 @@ export const useMobileRangePicker = <
   };
 
   const renderPicker = () => (
-    <LocalizationProvider localeText={localeText}>
+    <PickersProvider contextValue={contextValue} localeText={localeText}>
       <Field {...enrichedFieldProps} />
       <PickersModalDialog {...actions} open={open} slots={slots} slotProps={slotProps}>
         <Layout
@@ -226,7 +227,7 @@ export const useMobileRangePicker = <
           {renderCurrentView()}
         </Layout>
       </PickersModalDialog>
-    </LocalizationProvider>
+    </PickersProvider>
   );
 
   return {

packages/x-date-pickers/src/hooks/index.tsx

@@ -9,3 +9,7 @@ export type {
 export { usePickersTranslations } from './usePickersTranslations';
 
 export { useSplitFieldProps } from './useSplitFieldProps';
+
+export { useParsedFormat } from './useParsedFormat';
+
+export { usePickersContext } from './usePickersContext';

packages/x-date-pickers/src/hooks/useParsedFormat.ts

@@ -0,0 +1,61 @@
+'use client';
+import * as React from 'react';
+import { useRtl } from '@mui/system/RtlProvider';
+import { useUtils } from '../internals/hooks/useUtils';
+import { buildSectionsFromFormat } from '../internals/hooks/useField/buildSectionsFromFormat';
+import { getLocalizedDigits } from '../internals/hooks/useField/useField.utils';
+import { PickerValidDate } from '../models';
+import { usePickersTranslations } from './usePickersTranslations';
+import type { UseFieldInternalProps } from '../internals/hooks/useField';
+
+interface UseParsedFormatParameters
+  extends Pick<
+    UseFieldInternalProps<any, any, any, any, any>,
+    'format' | 'formatDensity' | 'shouldRespectLeadingZeros'
+  > {}
+
+/**
+ * Returns the parsed format to be rendered in the field when their is no value or in other parts of the picker.
+ * This format is localized (e.g: `AAAA` for the year with the French locale) and cannot be parsed by your date library.
+ * @param {object} The parameters needed to build the placeholder.
+ * @param {string} params.format Format of the date to use.
+ * @param {'dense' | 'spacious'} params.formatDensity Density of the format (setting `formatDensity` to `"spacious"` will add a space before and after each `/`, `-` and `.` character).
+ * @param {boolean} params.shouldRespectLeadingZeros If `true`, the format will respect the leading zeroes, if `false`, the format will always add leading zeroes.
+ * @returns
+ */
+export const useParsedFormat = <TDate extends PickerValidDate>(
+  parameters: UseParsedFormatParameters,
+) => {
+  const { format, formatDensity = 'dense', shouldRespectLeadingZeros = false } = parameters;
+  const utils = useUtils<TDate>();
+  const isRtl = useRtl();
+  const translations = usePickersTranslations<TDate>();
+  const localizedDigits = React.useMemo(() => getLocalizedDigits(utils), [utils]);
+
+  return React.useMemo(() => {
+    const sections = buildSectionsFromFormat({
+      utils,
+      format,
+      formatDensity,
+      isRtl,
+      shouldRespectLeadingZeros,
+      localeText: translations,
+      localizedDigits,
+      date: null,
+      // TODO v9: Make sure we still don't reverse in `buildSectionsFromFormat` when using `useParsedFormat`.
+      enableAccessibleFieldDOMStructure: false,
+    });
+
+    return sections
+      .map((section) => `${section.startSeparator}${section.placeholder}${section.endSeparator}`)
+      .join('');
+  }, [
+    utils,
+    isRtl,
+    translations,
+    localizedDigits,
+    format,
+    formatDensity,
+    shouldRespectLeadingZeros,
+  ]);
+};

packages/x-date-pickers/src/hooks/usePickersContext.ts

@@ -0,0 +1,19 @@
+'use client';
+import * as React from 'react';
+import { PickersContext } from '../internals/components/PickersProvider';
+
+/**
+ * Returns the context passed by the picker the wraps the current component.
+ */
+export const usePickersContext = () => {
+  const value = React.useContext(PickersContext);
+  if (value == null) {
+    throw new Error(
+      [
+        'MUI X: The `usePickersContext` can only be called in fields that are used as a slot of a picker component',
+      ].join('\n'),
+    );
+  }
+
+  return value;
+};