From a36fda43ca335d1c34dccdd1558e7636fb735815 Mon Sep 17 00:00:00 2001 From: flavien Date: Fri, 24 Jan 2025 15:54:21 +0100 Subject: [PATCH] [pickers] Improve the JSDoc of the PickerContextValue properties --- .../internals/components/PickerProvider.tsx | 35 +++++++++---------- .../hooks/usePicker/usePickerValue.types.ts | 17 +++++---- .../hooks/usePicker/usePickerViews.tsx | 11 ++++-- 3 files changed, 37 insertions(+), 26 deletions(-) diff --git a/packages/x-date-pickers/src/internals/components/PickerProvider.tsx b/packages/x-date-pickers/src/internals/components/PickerProvider.tsx index 30d4aa9be6735..230a811322af8 100644 --- a/packages/x-date-pickers/src/internals/components/PickerProvider.tsx +++ b/packages/x-date-pickers/src/internals/components/PickerProvider.tsx @@ -94,33 +94,32 @@ export interface PickerContextValue< > extends UsePickerValueContextValue, UsePickerViewsContextValue { /** - * `true` if the picker is disabled, `false` otherwise. + * Whether the picker is disabled. */ disabled: boolean; /** - * `true` if the picker is read-only, `false` otherwise. + * Whether the picker is read-only. */ readOnly: boolean; /** * The responsive variant of the picker. - * Is equal to "desktop" when using a desktop picker (like ). - * Is equal to "mobile" when using a mobile picker (like ). - * Is equal to "mobile" or "desktop" when using a responsive picker (like ) depending on the `desktopModeMediaQuery` prop. - * Is equal to "mobile" or "desktop" when using a static picker (like ) depending on the `displayStaticWrapperAs` prop. - * Is always equal to "desktop" if the component you are accessing the context from is not wrapped by a picker. + * It is equal to "desktop" when using a desktop picker (like ). + * It is equal to "mobile" when using a mobile picker (like ). + * It is equal to "mobile" or "desktop" when using a responsive picker (like ) depending on the `desktopModeMediaQuery` prop. + * It is equal to "mobile" or "desktop" when using a static picker (like ) depending on the `displayStaticWrapperAs` prop. + * It is always equal to "desktop" if the component you are accessing the context from is not wrapped by a picker. */ variant: PickerVariant; /** * The orientation of the picker. - * Is equal to "landscape" when the picker is in landscape orientation. - * Is equal to "portrait" when the picker is in portrait orientation. - * You can use the "orientation" on any picker component to force the orientation. - * Is always equal to "portrait" if the component you are accessing the context from is not wrapped by a picker. + * On Time Pickers and Date Time Pickers, it is always equal to "portrait". + * On Date Pickers, it is equal to the picker `orientation` prop if defined, otherwise it is based on the current orientation of the user's screen. + * It is always equal to "portrait" if the component you are accessing the context from is not wrapped by a picker. */ orientation: PickerOrientation; /** - * The ref that should be attached to the element that triggers the Picker opening. - * When using a built-in field component, this property is automatically handled. + * The ref to attach to the element that triggers the Picker opening. + * When using a built-in field component, this property is automatically attached to the right element. */ triggerRef: React.RefObject; /** @@ -131,11 +130,11 @@ export interface PickerContextValue< */ triggerStatus: 'hidden' | 'disabled' | 'enabled'; /** - * Format that should be used to render the value in the field. - * Is equal to `props.format` on the picker component if defined. - * Is generated based on the available views if not defined. - * Is equal to an empty string if the picker does not have a field (static pickers). - * Is always equal to an empty string if the component you are accessing the context from is not wrapped by a picker. + * The format to use when rendering the value in the field. + * It is equal to the picker `format` prop if defined. + * It is generated based on the available views if not defined. + * It is always equal to an empty string if the picker does not have a field (static pickers). + * It is always equal to an empty string if the component you are accessing the context from is not wrapped by a picker. */ fieldFormat: string; } diff --git a/packages/x-date-pickers/src/internals/hooks/usePicker/usePickerValue.types.ts b/packages/x-date-pickers/src/internals/hooks/usePicker/usePickerValue.types.ts index cc4c53b4da464..57be4e7a531b3 100644 --- a/packages/x-date-pickers/src/internals/hooks/usePicker/usePickerValue.types.ts +++ b/packages/x-date-pickers/src/internals/hooks/usePicker/usePickerValue.types.ts @@ -272,10 +272,15 @@ export interface UsePickerValueContextValue void; } export interface SetValueActionOptions { /** - * Importance of the change when picking a value: + * The importance of the change when picking a value: * - "accept": fires `onChange`, fires `onAccept` and closes the picker. * - "set": fires `onChange` but do not fire `onAccept` and does not close the picker. * @default "accept" @@ -339,16 +344,16 @@ export interface SetValueActionOptions { changeImportance?: PickerChangeImportance; /** * The validation error associated to the current value. - * If not defined, the validation will be re-applied by the picker. + * If not defined, the validation will be computed by the picker. */ validationError?: TError; /** * The shortcut that triggered this change. - * Should not be defined if the change does not come from a shortcut. + * It should not be defined if the change does not come from a shortcut. */ shortcut?: PickersShortcutsItemContext; /** - * Decide if the value should call `onChange` and `onAccept` when the value is not controlled and has never been modified. + * Whether the value should call `onChange` and `onAccept` when the value is not controlled and has never been modified. * If `true`, the `onChange` and `onAccept` callback will only be fired if the value has been modified (and is not equal to the last published value). * If `false`, the `onChange` and `onAccept` callback will be fired when the value has never been modified (`onAccept` only if `changeImportance` is set to "accept"). * @default false diff --git a/packages/x-date-pickers/src/internals/hooks/usePicker/usePickerViews.tsx b/packages/x-date-pickers/src/internals/hooks/usePicker/usePickerViews.tsx index f8769c0109b27..31ab6eccc772d 100644 --- a/packages/x-date-pickers/src/internals/hooks/usePicker/usePickerViews.tsx +++ b/packages/x-date-pickers/src/internals/hooks/usePicker/usePickerViews.tsx @@ -130,11 +130,18 @@ export interface UsePickerViewsActionsContextValue extends UsePickerViewsActionsContextValue { /** - * Available views. + * The views that the picker must render. + * It is equal to the picker `views` prop if defined. + * Otherwise, a default set of views is provided based on the component you are using: + * - Date Pickers: ['year', 'day'] + * - Time Pickers: ['hours', 'minutes'] + * - Date Time Pickers: ['year', 'day', 'hours', 'minutes'] + * - Date Range Pickers: ['day'] + * - Date Time Range Pickers: ['day', 'hours', 'minutes'] */ views: readonly TView[]; /** - * View currently rendered. + * The view currently rendered. */ view: TView | null; }