[pickers] Improve the JSDoc of the PickerContextValue properties (#16327)

Author: flaviendelangle

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

@@ -97,28 +97,27 @@ export interface PickerContextValue<
 > extends UsePickerValueContextValue<TValue, TError>,
     UsePickerViewsContextValue<TView> {
   /**
-   * `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 <DesktopDatePicker />).
-   * Is equal to "mobile" when using a mobile picker (like <MobileDatePicker />).
-   * Is equal to "mobile" or "desktop" when using a responsive picker (like <DatePicker />) depending on the `desktopModeMediaQuery` prop.
-   * Is equal to "mobile" or "desktop" when using a static picker (like <StaticDatePicker />) 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 <DesktopDatePicker />).
+   * It is equal to "mobile" when using a mobile picker (like <MobileDatePicker />).
+   * It is equal to "mobile" or "desktop" when using a responsive picker (like <DatePicker />) depending on the `desktopModeMediaQuery` prop.
+   * It is equal to "mobile" or "desktop" when using a static picker (like <StaticDatePicker />) 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;
   /**
@@ -127,8 +126,8 @@ export interface PickerContextValue<
    */
   reduceAnimations?: boolean;
   /**
-   * 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<any>;
   /**
@@ -139,11 +138,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;
 }

packages/x-date-pickers/src/internals/hooks/usePicker/usePickerValue.types.ts

@@ -272,10 +272,15 @@ export interface UsePickerValueContextValue<TValue extends PickerValidValue, TEr
   value: TValue;
   /**
    * The timezone to use when rendering the dates.
+   * If a `timezone` prop is provided, it will be used.
+   * If the `value` prop contains a valid date, its timezone will be used.
+   * If no `value` prop is provided, but the `defaultValue` contains a valid date, its timezone will be used.
+   * If no `value` or `defaultValue` is provided, but the `referenceDate` is provided, its timezone will be used.
+   * Otherwise, the timezone will be the default one of your date library.
    */
   timezone: PickersTimezone;
   /**
-   * `true` if the picker is open, `false` otherwise.
+   * Whether the picker is open.
    */
   open: boolean;
 }
@@ -324,31 +329,31 @@ export interface UsePickerValueActionsContextValue<TValue extends PickerValidVal
 
 export interface UsePickerValuePrivateContextValue {
   /**
-   * Closes the picker and accepts the current value if it is not equal to the last accepted value.
+   * Close the picker and accepts the current value if it is not equal to the last accepted value.
    */
   dismissViews: () => void;
 }
 
 export interface SetValueActionOptions<TError = string | null> {
   /**
-   * 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"
    */
   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

packages/x-date-pickers/src/internals/hooks/usePicker/usePickerViews.tsx

@@ -124,11 +124,18 @@ export interface UsePickerViewsActionsContextValue<TView extends DateOrTimeViewW
 export interface UsePickerViewsContextValue<TView extends DateOrTimeViewWithMeridiem>
   extends UsePickerViewsActionsContextValue<TView> {
   /**
-   * 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;
 }