Review Lukas + JSDoc for useParsedFormat

Author: flaviendelangle

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

@@ -7,7 +7,7 @@ import { DatePicker } from '@mui/x-date-pickers/DatePicker';
 import { useValidation, validateDate } from '@mui/x-date-pickers/validation';
 import {
   useSplitFieldProps,
-  useFieldPlaceholder,
+  useParsedFormat,
   usePickersContext,
 } from '@mui/x-date-pickers/hooks';
 
@@ -18,7 +18,7 @@ function ReadOnlyDateField(props) {
 
   const pickersContext = usePickersContext();
 
-  const placeholder = useFieldPlaceholder(internalProps);
+  const parsedFormat = useParsedFormat(internalProps);
   const { hasValidationError } = useValidation({
     validator: validateDate,
     value,
@@ -30,7 +30,7 @@ function ReadOnlyDateField(props) {
     <TextField
       {...other}
       value={value == null ? '' : value.format(format)}
-      placeholder={placeholder}
+      placeholder={parsedFormat}
       InputProps={{ ...InputProps, readOnly: true }}
       error={hasValidationError}
       onClick={pickersContext.onToggleView}

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

@@ -11,7 +11,7 @@ import {
 import { useValidation, validateDate } from '@mui/x-date-pickers/validation';
 import {
   useSplitFieldProps,
-  useFieldPlaceholder,
+  useParsedFormat,
   usePickersContext,
 } from '@mui/x-date-pickers/hooks';
 
@@ -22,7 +22,7 @@ function ReadOnlyDateField(props: DatePickerFieldProps<Dayjs, false>) {
 
   const pickersContext = usePickersContext();
 
-  const placeholder = useFieldPlaceholder(internalProps);
+  const parsedFormat = useParsedFormat(internalProps);
   const { hasValidationError } = useValidation({
     validator: validateDate,
     value,
@@ -34,7 +34,7 @@ function ReadOnlyDateField(props: DatePickerFieldProps<Dayjs, false>) {
     <TextField
       {...other}
       value={value == null ? '' : value.format(format)}
-      placeholder={placeholder}
+      placeholder={parsedFormat}
       InputProps={{ ...InputProps, readOnly: true }}
       error={hasValidationError}
       onClick={pickersContext.onToggleView}

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

@@ -93,7 +93,7 @@ export const useDesktopRangePicker = <
     renderCurrentView,
     shouldRestoreFocus,
     fieldProps: pickerFieldProps,
-    fieldContextValue,
+    contextValue,
   } = usePicker<
     DateRange<TDate>,
     TDate,
@@ -210,7 +210,7 @@ export const useDesktopRangePicker = <
   const Layout = slots?.layout ?? PickersLayout;
 
   const renderPicker = () => (
-    <PickersProvider fieldContextValue={fieldContextValue} localeText={localeText}>
+    <PickersProvider contextValue={contextValue} localeText={localeText}>
       <Field {...enrichedFieldProps} />
       <PickersPopper
         role="tooltip"

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

@@ -88,7 +88,7 @@ export const useMobileRangePicker = <
     layoutProps,
     renderCurrentView,
     fieldProps: pickerFieldProps,
-    fieldContextValue,
+    contextValue,
   } = usePicker<
     DateRange<TDate>,
     TDate,
@@ -215,7 +215,7 @@ export const useMobileRangePicker = <
   };
 
   const renderPicker = () => (
-    <PickersProvider fieldContextValue={fieldContextValue} localeText={localeText}>
+    <PickersProvider contextValue={contextValue} localeText={localeText}>
       <Field {...enrichedFieldProps} />
       <PickersModalDialog {...actions} open={open} slots={slots} slotProps={slotProps}>
         <Layout

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

@@ -10,6 +10,6 @@ export { usePickersTranslations } from './usePickersTranslations';
 
 export { useSplitFieldProps } from './useSplitFieldProps';
 
-export { useFieldPlaceholder } from './useFieldPlaceholder';
+export { useParsedFormat } from './useParsedFormat';
 
 export { usePickersContext } from './usePickersContext';

packages/x-date-pickers/src/hooks/useFieldPlaceholder.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/useParsedFormat.ts

@@ -7,25 +7,25 @@ export const PickersContext = React.createContext<PickersContextValue | null>(nu
 
 /**
  * Provides the context for the various parts of a picker component:
- * - fieldContextValue: the context for the field
+ * - contextValue: the context for the picker sub-components.
  * - localizationProvider: the translations passed through the props and through a parent LocalizationProvider.
  *
  * @ignore - do not document.
  */
 export function PickersProvider<TDate extends PickerValidDate>(
   props: PickersFieldProviderProps<TDate>,
 ) {
-  const { fieldContextValue, localeText, children } = props;
+  const { contextValue, localeText, children } = props;
 
   return (
-    <PickersContext.Provider value={fieldContextValue}>
+    <PickersContext.Provider value={contextValue}>
       <LocalizationProvider localeText={localeText}>{children}</LocalizationProvider>
     </PickersContext.Provider>
   );
 }
 
 interface PickersFieldProviderProps<TDate extends PickerValidDate> {
-  fieldContextValue: PickersContextValue;
+  contextValue: PickersContextValue;
   localeText: PickersInputLocaleText<TDate> | undefined;
   children: React.ReactNode;
 }

packages/x-date-pickers/src/internals/components/PickersProvider.tsx

@@ -80,7 +80,7 @@ export const useDesktopPicker = <
     renderCurrentView,
     shouldRestoreFocus,
     fieldProps: pickerFieldProps,
-    fieldContextValue,
+    contextValue,
   } = usePicker<TDate | null, TDate, TView, FieldSection, TExternalProps, {}>({
     ...pickerParams,
     props,
@@ -213,7 +213,7 @@ export const useDesktopPicker = <
   const handleFieldRef = useForkRef(fieldRef, fieldProps.unstableFieldRef);
 
   const renderPicker = () => (
-    <PickersProvider fieldContextValue={fieldContextValue} localeText={localeText}>
+    <PickersProvider contextValue={contextValue} localeText={localeText}>
       <Field
         {...fieldProps}
         slots={slotsForField}

packages/x-date-pickers/src/internals/hooks/useDesktopPicker/useDesktopPicker.tsx

@@ -1,4 +1,4 @@
-import { FieldSection, MuiPickersAdapter, PickersTimezone, PickerValidDate } from '../../../models';
+import { FieldSection, MuiPickersAdapter, PickerValidDate } from '../../../models';
 import { PickersLocaleText } from '../../../locales';
 import {
   applyLocalizedDigits,
@@ -13,7 +13,6 @@ interface BuildSectionsFromFormatParams<TDate extends PickerValidDate> {
   format: string;
   formatDensity: 'dense' | 'spacious';
   isRtl: boolean;
-  timezone: PickersTimezone;
   shouldRespectLeadingZeros: boolean;
   localeText: PickersLocaleText<TDate>;
   localizedDigits: string[];
@@ -64,15 +63,14 @@ const getEscapedPartsFromFormat = <TDate extends PickerValidDate>({
 
 const getSectionPlaceholder = <TDate extends PickerValidDate>(
   utils: MuiPickersAdapter<TDate>,
-  timezone: PickersTimezone,
   localeText: PickersLocaleText<TDate>,
   sectionConfig: Pick<FieldSection, 'type' | 'contentType'>,
   sectionFormat: string,
 ) => {
   switch (sectionConfig.type) {
     case 'year': {
       return localeText.fieldYearPlaceholder({
-        digitAmount: utils.formatByString(utils.date(undefined, timezone), sectionFormat).length,
+        digitAmount: utils.formatByString(utils.date(undefined, 'default'), sectionFormat).length,
         format: sectionFormat,
       });
     }
@@ -119,7 +117,6 @@ const getSectionPlaceholder = <TDate extends PickerValidDate>(
 
 const createSection = <TDate extends PickerValidDate>({
   utils,
-  timezone,
   date,
   shouldRespectLeadingZeros,
   localeText,
@@ -140,7 +137,6 @@ const createSection = <TDate extends PickerValidDate>({
 
   const hasLeadingZerosInFormat = doesSectionFormatHaveLeadingZeros(
     utils,
-    timezone,
     sectionConfig.contentType,
     sectionConfig.type,
     token,
@@ -181,7 +177,7 @@ const createSection = <TDate extends PickerValidDate>({
     format: token,
     maxLength,
     value: sectionValue,
-    placeholder: getSectionPlaceholder(utils, timezone, localeText, sectionConfig, token),
+    placeholder: getSectionPlaceholder(utils, localeText, sectionConfig, token),
     hasLeadingZerosInFormat,
     hasLeadingZerosInInput,
     startSeparator,