From ad996b022848fda32430792d1bc6147915a45cad Mon Sep 17 00:00:00 2001 From: delangle Date: Wed, 19 Jun 2024 13:49:45 +0200 Subject: [PATCH] [docs] Improve the documentation of the picker's onChange and onAccept props --- docs/data/date-pickers/lifecycle/lifecycle.md | 87 +++++++++++++++---- packages/x-date-pickers/src/models/pickers.ts | 2 +- 2 files changed, 72 insertions(+), 17 deletions(-) diff --git a/docs/data/date-pickers/lifecycle/lifecycle.md b/docs/data/date-pickers/lifecycle/lifecycle.md index 7cb1c3acc171..e3be8f43678a 100644 --- a/docs/data/date-pickers/lifecycle/lifecycle.md +++ b/docs/data/date-pickers/lifecycle/lifecycle.md @@ -44,13 +44,15 @@ Note how changing the value of the start date section will call `onChange` even ## Pickers lifecycle -### When is `onClose` called? +### `onClose` + +#### When is `onClose` called? :::info In all the below scenarios, the picker closes when `onClose` is called, except if you are controlling the `open` prop. ::: -#### When the last view is completed +##### When the last view is completed When a selection in the last view is made, `onClose` will be called only if the `closeOnSelect` prop is equal to `true`. By default, it is set to `true` on desktop and `false` on mobile. @@ -124,27 +126,55 @@ For example, on the `DatePicker`, the `year` and `month` views are not in the de so the picker will close even if you never went to those views. ::: -#### When the picker is manually closed +##### When the picker is manually closed Pressing Escape or clicking outside the picker will close the picker. -#### When a value is selected using the action bar +##### When a value is selected using the action bar Clicking on any built-in button of the action bar will close the picker. -#### When a shortcut is picked +##### When a shortcut is picked Clicking on a shortcut will close the picker, except if the `changeImportance` property has been set to `"set"` instead of the default value `"accept"`. You can find more information [in the dedicated doc section](/x/react-date-pickers/shortcuts/#behavior-when-selecting-a-shortcut). -### When is `onChange` called? +### `onChange` + +#### Usage + +The `onChange` callback is called whenever the current value changes. + +If you don't want to listen to the intermediary steps, consider using the [`onAccept` prop](/x/react-date-pickers/lifecycle/#onaccept) instead. + +```tsx + setValue(value)} /> +``` + +:::success +You can use the second argument passed to the `onChange` callback to get the validation error associated with the current value: + +```tsx + { + setValue(value); + if (context.validationError == null) { + runSomeLogic(); + } + }} +/> +``` + +::: + +#### When is `onChange` called? -#### When the field calls `onChange` +##### When the field calls `onChange` When editing your value through the input(s) of your field, the picker will just re-publish the `onChange` callback. Take a look at the [dedicated section](/x/react-date-pickers/lifecycle/#fields-lifecycle) for more information. -#### When the user interacts with the view +##### When the user interacts with the view If the component is controlled (i.e: if it has a `value` prop), clicking on a value will call `onChange` if the value to publish is different from the current value @@ -157,21 +187,46 @@ Some views can decide not to call `onChange` for some value modifications. The most common example is the mobile time views (using the [`TimeClock`](/x/react-date-pickers/time-clock/) component). The `onChange` is only fired once when the dragging (touching) of the clock hand ends even though the UI updates on each position change. -#### When a value is selected using the action bar +##### When a value is selected using the action bar If the component is controlled (i.e: if it has a `value` prop), clicking on any built-in actions will call `onChange` if the value to publish is different from the current value. If the component is not controlled, the behavior is the same, except for the _Clear_, _Today_, and _OK_ actions that will call `onChange` if no value has ever been published, even if the current value equals the value to publish. -#### When a shortcut is picked +##### When a shortcut is picked Clicking on a shortcut will call `onChange`. You can find more information [in the dedicated doc section](/x/react-date-pickers/shortcuts/#behavior-when-selecting-a-shortcut). -### When is `onAccept` called? +### `onAccept` + +#### Usage + +The `onAccept` callback allows you to get the final value selected by the user without caring about the intermediary steps. + +```tsx + sendValueToServer(value)} /> +``` + +:::success +You can use the second argument passed to the `onAccept` callback to get the validation error associated with the current value: + +```tsx + { + if (context.validationError == null) { + runSomeLogic(); + } + }} +/> +``` + +::: + +#### When is `onAccept` called? -#### When the last view is completed +##### When the last view is completed When a selection in the last view is made, `onAccept` will be called only if the `closeOnSelect` prop is equal to `true` and the value has been modified since the last time `onAccept` was called. By default, `closeOnSelect`, is set to `true` on desktop and `false` on mobile. @@ -230,21 +285,21 @@ The examples below are using the desktop and mobile variants of the pickers, but **Behavior:** The picker will call `onAccept` when selecting the minutes or meridiem (if a 12-hour clock is used). -#### When the picker is manually closed +##### When the picker is manually closed When the user presses Escape or clicks outside the picker, `onAccept` is called with: - the current value, if the last view has been completed - the last accepted value, if the last view has not been completed -#### When a value is selected using the action bar +##### When a value is selected using the action bar If the component is controlled (i.e: if it has a `value` prop), clicking on any built-in actions will call `onAccept` if the value to publish is different from the current value. If the component is not controlled, the behavior is the same, except for the _Clear_, _Today_, and _OK_ actions that will call `onAccept` if no value has ever been published, even if the current value equals the value to publish. -#### When a shortcut is picked +##### When a shortcut is picked Clicking on a shortcut will call `onAccept`, except if the `changeImportance` property has been set to `"set"` instead of `"accept"`. You can find more information [in the dedicated doc section](/x/react-date-pickers/shortcuts/#behavior-when-selecting-a-shortcut). @@ -341,6 +396,6 @@ In such a case, the recommended UI is to add a button for validating the form. If for some reason, you need to send the data to the server without having the user pressing a validation button, you can debounce the `onChange` as follows. The following demo shows how to extend the Date Field component by adding an `onAccept` prop, which is a debounced version of `onChange`. -You can find more information about the `onAccept` prop [in the dedicated doc section](/x/react-date-pickers/lifecycle/#when-is-onaccept-called). +You can find more information about the `onAccept` prop [in the dedicated doc section](/x/react-date-pickers/lifecycle/#onaccept). {{"demo": "ServerInteraction.js"}} diff --git a/packages/x-date-pickers/src/models/pickers.ts b/packages/x-date-pickers/src/models/pickers.ts index f093acb08b6f..db341d045e20 100644 --- a/packages/x-date-pickers/src/models/pickers.ts +++ b/packages/x-date-pickers/src/models/pickers.ts @@ -3,7 +3,7 @@ import type { PickersShortcutsItemContext } from '../PickersShortcuts'; export interface PickerChangeHandlerContext { validationError: TError; /** - * Shortcut causing this `onChange` call. + * Shortcut causing this `onChange` or `onAccept` call. * If the call has not been caused by a shortcut selection, this property will be `undefined`. */ shortcut?: PickersShortcutsItemContext;