@mui/x-date-pickers 6.0.4 → 6.2.0

package/internals/hooks/usePicker/usePickerValue.types.d.ts

@@ -0,0 +1,233 @@
+import { FieldChangeHandlerContext, UseFieldInternalProps } from '../useField';
+import { InferError, Validator } from '../validation/useValidation';
+import { UseFieldValidationProps } from '../useField/useField.types';
+import { WrapperVariant } from '../../models/common';
+import { FieldSection, FieldSelectedSections, MuiPickersAdapter } from '../../../models';
+export interface PickerValueManager<TValue, TDate, TError> {
+    /**
+     * Determines if two values are equal.
+     * @template TDate, TValue
+     * @param {MuiPickersAdapter<TDate>} utils The adapter.
+     * @param {TValue} valueLeft The first value to compare.
+     * @param {TValue} valueRight The second value to compare.
+     * @returns {boolean} A boolean indicating if the two values are equal.
+     */
+    areValuesEqual: (utils: MuiPickersAdapter<TDate>, valueLeft: TValue, valueRight: TValue) => boolean;
+    /**
+     * Value to set when clicking the "Clear" button.
+     */
+    emptyValue: TValue;
+    /**
+     * Method returning the value to set when clicking the "Today" button
+     * @template TDate, TValue
+     * @param {MuiPickersAdapter<TDate>} utils The adapter.
+     * @returns {TValue} The value to set when clicking the "Today" button.
+     */
+    getTodayValue: (utils: MuiPickersAdapter<TDate>) => TValue;
+    /**
+     * Method parsing the input value to replace all invalid dates by `null`.
+     * @template TDate, TValue
+     * @param {MuiPickersAdapter<TDate>} utils The adapter.
+     * @param {TValue} value The value to parse.
+     * @returns {TValue} The value without invalid date.
+     */
+    cleanValue: (utils: MuiPickersAdapter<TDate>, value: TValue) => TValue;
+    /**
+     * Generates the new value, given the previous value and the new proposed value.
+     * @template TDate, TValue
+     * @param {MuiPickersAdapter<TDate>} utils The adapter.
+     * @param {TValue} lastValidDateValue The last valid value.
+     * @param {TValue} value The proposed value.
+     * @returns {TValue} The new value.
+     */
+    valueReducer?: (utils: MuiPickersAdapter<TDate>, lastValidDateValue: TValue, value: TValue) => TValue;
+    /**
+     * Compare two errors to know if they are equal.
+     * @template TError
+     * @param {TError} error The new error
+     * @param {TError | null} prevError The previous error
+     * @returns {boolean} `true` if the new error is different from the previous one.
+     */
+    isSameError: (error: TError, prevError: TError | null) => boolean;
+    /**
+     * Checks if the current error is empty or not.
+     * @template TError
+     * @param {TError} error The current error.
+     * @returns {boolean} `true` if the current error is not empty.
+     */
+    hasError: (error: TError) => boolean;
+    /**
+     * The value identifying no error, used to initialise the error state.
+     */
+    defaultErrorState: TError;
+}
+export interface PickerChangeHandlerContext<TError> {
+    validationError: TError;
+}
+export type PickerSelectionState = 'partial' | 'shallow' | 'finish';
+export interface UsePickerValueState<TValue> {
+    /**
+     * Date displayed on the views and the field.
+     * It is updated whenever the user modifies something.
+     */
+    draft: TValue;
+    /**
+     * Last value published (e.g: the last value for which `shouldPublishValue` returned `true`).
+     * If `onChange` is defined, it's the value that was passed on the last call to this callback.
+     */
+    lastPublishedValue: TValue;
+    /**
+     * Last value committed (e.g: the last value for which `shouldCommitValue` returned `true`).
+     * If `onAccept` is defined, it's the value that was passed on the last call to this callback.
+     */
+    lastCommittedValue: TValue;
+    /**
+     * Last value passed with `props.value`.
+     * Used to update the `draft` value whenever the `value` prop changes.
+     */
+    lastControlledValue: TValue | undefined;
+    /**
+     * If we never modified the value since the mount of the component,
+     * Then we might want to apply some custom logic.
+     *
+     * For example, when the component is not controlled and `defaultValue` is defined.
+     * Then clicking on "Accept", "Today" or "Clear" should fire `onAccept` with `defaultValue`, but clicking on "Cancel" or dimissing the picker should not.
+     */
+    hasBeenModifiedSinceMount: boolean;
+}
+export interface PickerValueUpdaterParams<TValue, TError> {
+    action: PickerValueUpdateAction<TValue, TError>;
+    dateState: UsePickerValueState<TValue>;
+    /**
+     * Check if the new draft value has changed compared to some given value.
+     * @template TValue
+     * @param {TValue} comparisonValue The value to compare the new draft value with.
+     * @returns {boolean} `true` if the new draft value is equal to the comparison value.
+     */
+    hasChanged: (comparisonValue: TValue) => boolean;
+    isControlled: boolean;
+    closeOnSelect: boolean;
+}
+export type PickerValueUpdateAction<TValue, TError> = {
+    name: 'setValueFromView';
+    value: TValue;
+    selectionState: PickerSelectionState;
+} | {
+    name: 'setValueFromField';
+    value: TValue;
+    context: FieldChangeHandlerContext<TError>;
+} | {
+    name: 'setValueFromAction';
+    value: TValue;
+    pickerAction: 'accept' | 'today' | 'cancel' | 'dismiss' | 'clear';
+};
+/**
+ * Props used to handle the value that are common to all pickers.
+ */
+export interface UsePickerValueBaseProps<TValue, TError> {
+    /**
+     * The selected value.
+     * Used when the component is controlled.
+     */
+    value?: TValue;
+    /**
+     * The default value.
+     * Used when the component is not controlled.
+     */
+    defaultValue?: TValue;
+    /**
+     * Callback fired when the value changes.
+     * @template TValue The value type. Will be either the same type as `value` or `null`. Can be in `[start, end]` format in case of range value.
+     * @template TError The validation error type. Will be either `string` or a `null`. Can be in `[start, end]` format in case of range value.
+     * @param {TValue} value The new value.
+     * @param {FieldChangeHandlerContext<TError>} context The context containing the validation result of the current value.
+     */
+    onChange?: (value: TValue, context: PickerChangeHandlerContext<TError>) => void;
+    /**
+     * Callback fired when the value is accepted.
+     * @template TValue The value type. Will be either the same type as `value` or `null`. Can be in `[start, end]` format in case of range value.
+     * @param {TValue} value The value that was just accepted.
+     */
+    onAccept?: (value: TValue) => void;
+    /**
+     * Callback fired when the error associated to the current value changes.
+     * If the error has a non-null value, then the `TextField` will be rendered in `error` state.
+     *
+     * @template TValue The value type. Will be either the same type as `value` or `null`. Can be in `[start, end]` format in case of range value.
+     * @template TError The validation error type. Will be either `string` or a `null`. Can be in `[start, end]` format in case of range value.
+     * @param {TError} error The new error describing why the current value is not valid.
+     * @param {TValue} value The value associated to the error.
+     */
+    onError?: (error: TError, value: TValue) => void;
+}
+/**
+ * Props used to handle the value of non-static pickers.
+ */
+export interface UsePickerValueNonStaticProps<TValue, TSection extends FieldSection> extends Pick<UseFieldInternalProps<TValue, TSection, unknown>, 'selectedSections' | 'onSelectedSectionsChange'> {
+    /**
+     * If `true`, the popover or modal will close after submitting the full date.
+     * @default `true` for desktop, `false` for mobile (based on the chosen wrapper and `desktopModeMediaQuery` prop).
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Control the popup or dialog open state.
+     * @default false
+     */
+    open?: boolean;
+    /**
+     * Callback fired when the popup requests to be closed.
+     * Use in controlled mode (see `open`).
+     */
+    onClose?: () => void;
+    /**
+     * Callback fired when the popup requests to be opened.
+     * Use in controlled mode (see `open`).
+     */
+    onOpen?: () => void;
+}
+/**
+ * Props used to handle the value of the pickers.
+ */
+export interface UsePickerValueProps<TValue, TSection extends FieldSection, TError> extends UsePickerValueBaseProps<TValue, TError>, UsePickerValueNonStaticProps<TValue, TSection> {
+}
+export interface UsePickerValueParams<TValue, TDate, TSection extends FieldSection, TExternalProps extends UsePickerValueProps<TValue, TSection, any>> {
+    props: TExternalProps;
+    valueManager: PickerValueManager<TValue, TDate, InferError<TExternalProps>>;
+    wrapperVariant: WrapperVariant;
+    validator: Validator<TValue, TDate, InferError<TExternalProps>, UseFieldValidationProps<TValue, TExternalProps>>;
+}
+export interface UsePickerValueActions {
+    onAccept: () => void;
+    onClear: () => void;
+    onDismiss: () => void;
+    onCancel: () => void;
+    onSetToday: () => void;
+    onOpen: () => void;
+    onClose: () => void;
+}
+export type UsePickerValueFieldResponse<TValue, TSection extends FieldSection, TError> = Required<Pick<UseFieldInternalProps<TValue, TSection, TError>, 'value' | 'onChange' | 'selectedSections' | 'onSelectedSectionsChange'>>;
+/**
+ * Props passed to `usePickerViews`.
+ */
+export interface UsePickerValueViewsResponse<TValue> {
+    value: TValue;
+    onChange: (value: TValue, selectionState?: PickerSelectionState) => void;
+    open: boolean;
+    onClose: () => void;
+    onSelectedSectionsChange: (newValue: FieldSelectedSections) => void;
+}
+/**
+ * Props passed to `usePickerLayoutProps`.
+ */
+export interface UsePickerValueLayoutResponse<TValue> extends UsePickerValueActions {
+    value: TValue;
+    onChange: (newValue: TValue) => void;
+    isValid: (value: TValue) => boolean;
+}
+export interface UsePickerValueResponse<TValue, TSection extends FieldSection, TError> {
+    open: boolean;
+    actions: UsePickerValueActions;
+    viewProps: UsePickerValueViewsResponse<TValue>;
+    fieldProps: UsePickerValueFieldResponse<TValue, TSection, TError>;
+    layoutProps: UsePickerValueLayoutResponse<TValue>;
+}

package/internals/hooks/usePicker/usePickerValue.types.js

@@ -0,0 +1 @@
+export {};

package/internals/hooks/usePicker/usePickerViews.d.ts

@@ -3,7 +3,7 @@ import { SxProps } from '@mui/system';
 import { Theme } from '@mui/material/styles';
 import { DateOrTimeView } from '../../../models';
 import { UseViewsOptions } from '../useViews';
-import type { UsePickerValueViewsResponse } from './usePickerValue';
+import type { UsePickerValueViewsResponse } from './usePickerValue.types';
 interface PickerViewsRendererBaseExternalProps<TView extends DateOrTimeView> extends Omit<UsePickerViewsProps<any, TView, any, any>, 'openTo' | 'viewRenderers'> {
 }
 export type PickerViewsRendererProps<TValue, TView extends DateOrTimeView, TExternalProps extends PickerViewsRendererBaseExternalProps<TView>, TAdditionalProps extends {}> = TExternalProps & TAdditionalProps & UsePickerValueViewsResponse<TValue> & {

package/internals/hooks/usePicker/usePickerViews.js

@@ -6,6 +6,19 @@ import useEnhancedEffect from '@mui/utils/useEnhancedEffect';
 import useEventCallback from '@mui/utils/useEventCallback';
 import { useViews } from '../useViews';
 import { isTimeView } from '../../utils/time-utils';
+
+/**
+ * Props used to handle the views that are common to all pickers.
+ */
+
+/**
+ * Props used to handle the views of the pickers.
+ */
+
+/**
+ * Props used to handle the value of the pickers.
+ */
+
 /**
  * Manage the views of all the pickers:
  * - Handles the view switch

package/internals/hooks/useUtils.d.ts

@@ -3,7 +3,7 @@ import { PickersLocaleText } from '../../locales/utils/pickersLocaleTextApi';
 export declare const useLocalizationContext: <TDate>() => Omit<MuiPickersAdapterContextValue<TDate>, "localeText"> & {
     localeText: PickersLocaleText<TDate>;
 };
-export declare const useUtils: <TDate>() => import("..").MuiPickersAdapter<TDate>;
+export declare const useUtils: <TDate>() => import("../..").MuiPickersAdapter<TDate>;
 export declare const useDefaultDates: <TDate>() => {
     minDate: TDate;
     maxDate: TDate;

package/internals/index.d.ts

@@ -27,7 +27,7 @@ export type { UseFieldInternalProps, UseFieldParams, UseFieldResponse, UseFieldF
 export type { MobileOnlyPickerProps } from './hooks/useMobilePicker';
 export { usePicker } from './hooks/usePicker';
 export type { UsePickerResponse, UsePickerParams, UsePickerProps } from './hooks/usePicker';
-export type { UsePickerValueNonStaticProps, PickerValueManager, PickerSelectionState, } from './hooks/usePicker/usePickerValue';
+export type { UsePickerValueNonStaticProps, PickerValueManager, PickerSelectionState, } from './hooks/usePicker/usePickerValue.types';
 export type { UsePickerViewsNonStaticProps, PickerViewRendererLookup, UsePickerViewsProps, } from './hooks/usePicker/usePickerViews';
 export { useStaticPicker } from './hooks/useStaticPicker';
 export type { StaticOnlyPickerProps, UseStaticPickerSlotsComponent, UseStaticPickerSlotsComponentsProps, } from './hooks/useStaticPicker';
@@ -43,7 +43,6 @@ export { usePreviousMonthDisabled, useNextMonthDisabled } from './hooks/date-hel
 export type { BaseFieldProps, FieldsTextFieldProps } from './models/fields';
 export type { BasePickerProps, BasePickerInputProps, BaseNonStaticPickerProps, } from './models/props/basePickerProps';
 export type { BaseToolbarProps, ExportedBaseToolbarProps } from './models/props/toolbar';
-export type { MuiPickersAdapter } from './models/muiPickersAdapter';
 export type { DefaultizedProps, MakeOptional } from './models/helpers';
 export type { WrapperVariant } from './models/common';
 export { applyDefaultDate, replaceInvalidDateByNull, areDatesEqual } from './utils/date-utils';

package/internals/models/index.d.ts

@@ -1,2 +1 @@
 export * from './fields';
-export * from './muiPickersAdapter';

package/internals/models/index.js

@@ -1,2 +1 @@
-export * from './fields';
-export * from './muiPickersAdapter';
+export * from './fields';

package/internals/models/props/basePickerProps.d.ts

@@ -39,6 +39,12 @@ export interface BaseNonStaticPickerProps {
      * Defaults to localized format based on the used `views`.
      */
     format?: string;
+    /**
+     * Density of the format when rendered in the input.
+     * Setting `formatDensity` to `"spacious"` will add a space before and after each `/`, `-` and `.` character.
+     * @default "dense"
+     */
+    formatDensity?: 'dense' | 'spacious';
 }
 /**
  * Props common to all non-range non-static pickers.

package/internals/utils/date-utils.d.ts

@@ -1,4 +1,4 @@
-import { MuiPickersAdapter } from '../models';
+import { MuiPickersAdapter } from '../../models';
 interface FindClosestDateParams<TDate> {
     date: TDate;
     disableFuture?: boolean;

package/internals/utils/time-utils.d.ts

@@ -1,5 +1,4 @@
-import { MuiPickersAdapter } from '../models';
-import { DateOrTimeView } from '../../models';
+import { DateOrTimeView, MuiPickersAdapter } from '../../models';
 export declare const isTimeView: (view: DateOrTimeView) => boolean;
 type Meridiem = 'am' | 'pm' | null;
 export declare const getMeridiem: <TDate>(date: TDate | null, utils: MuiPickersAdapter<TDate>) => Meridiem;

package/internals/utils/valueManagers.d.ts

@@ -3,4 +3,4 @@ import { DateValidationError, TimeValidationError, DateTimeValidationError, Fiel
 import type { FieldValueManager } from '../hooks/useField';
 export type SingleItemPickerValueManager<TValue = any, TDate = any, TError extends DateValidationError | TimeValidationError | DateTimeValidationError = any> = PickerValueManager<TValue, TDate, TError>;
 export declare const singleItemValueManager: SingleItemPickerValueManager;
-export declare const singleItemFieldValueManager: FieldValueManager<any, any, FieldSection, DateValidationError | TimeValidationError | DateTimeValidationError>;
+export declare const singleItemFieldValueManager: FieldValueManager<any, any, FieldSection>;

package/internals/utils/valueManagers.js

@@ -6,6 +6,7 @@ export const singleItemValueManager = {
   cleanValue: replaceInvalidDateByNull,
   areValuesEqual: areDatesEqual,
   isSameError: (a, b) => a === b,
+  hasError: error => error != null,
   defaultErrorState: null
 };
 export const singleItemFieldValueManager = {
@@ -27,6 +28,5 @@ export const singleItemFieldValueManager = {
       referenceValue: newActiveDate == null || !utils.isValid(newActiveDate) ? state.referenceValue : newActiveDate
     })
   }),
-  parseValueStr: (valueStr, referenceValue, parseDate) => parseDate(valueStr.trim(), referenceValue),
-  hasError: error => error != null
+  parseValueStr: (valueStr, referenceValue, parseDate) => parseDate(valueStr.trim(), referenceValue)
 };