From 46805904d697c9b0a99e4d2dbd14106449380798 Mon Sep 17 00:00:00 2001
From: flavien <flaviendelangle@gmail.com>
Date: Wed, 4 Dec 2024 08:55:03 +0100
Subject: [PATCH] Add migration guide

---
 .../migration-pickers-v7.md                   | 40 +++++++++++++++++++
 .../hooks/usePicker/usePickerValue.types.ts   | 11 ++++-
 .../models/props/basePickerProps.tsx          | 12 ++++++
 3 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/docs/data/migration/migration-pickers-v7/migration-pickers-v7.md b/docs/data/migration/migration-pickers-v7/migration-pickers-v7.md
index 764f28cfb98a..411d78148105 100644
--- a/docs/data/migration/migration-pickers-v7/migration-pickers-v7.md
+++ b/docs/data/migration/migration-pickers-v7/migration-pickers-v7.md
@@ -404,6 +404,46 @@ The following variables and types have been renamed to have a coherent `Picker`
   +import { FieldRangeSection } from '@mui/x-date-pickers-pro';
   ```
 
+## Hooks breaking changes
+
+### `usePickerContext`
+
+- The `onOpen` and `onClock` methods have been replaced with a single `setOpen` method.
+  This method no longer takes an event, which was used to prevent the browser default behavior:
+
+  ```diff
+  const pickerContext = usePickerContext();
+
+  -<button onClick={pickerContext.onOpen}>Open</button>
+  +<button onClick={() => pickerContext.setOpen(true)}>Open</button>
+
+  -<button onClick={pickerContext.onClose}>Close</button>
+  +<button onClick={() => pickerContext.setOpen(false)}>Open</button>
+
+  -<button
+  -  onClick={(event) =>
+  -    pickerContext.open ? pickerContext.onClose(event) : pickerContext.onOpen(event)
+  -  }
+  ->
+  -  Toggle
+  -</button>
+  +<button onClick={() => pickerContext.setOpen(prev => !prev)}>Toggle</button>
+  ```
+
+  If you want to prevent the default behavior, you now have to do it manually:
+
+  ```diff
+     <div
+     onKeyDown={(event) => {
+       if (event.key === 'Escape') {
+  -      pickerContext.onClose();
+  +      event.preventDefault();
+  +      pickerContext.setOpen(false);
+       }
+     }}
+   />
+  ```
+
 ## Typing breaking changes
 
 ### Do not pass the date object as a generic
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 5550c7535fa6..60c022e497a9 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
@@ -1,3 +1,4 @@
+import * as React from 'react';
 import { FieldChangeHandlerContext, UseFieldInternalProps } from '../useField';
 import { Validator } from '../../../validation';
 import { PickerVariant } from '../../models/common';
@@ -17,7 +18,6 @@ import {
   PickersShortcutsItemContext,
 } from '../../../PickersShortcuts';
 import { InferNonNullablePickerValue, PickerValidValue } from '../../models';
-import React from 'react';
 
 export interface PickerValueManager<TValue extends PickerValidValue, TError> {
   /**
@@ -332,6 +332,15 @@ export interface UsePickerValueResponse<TValue extends PickerValidValue, TError>
 }
 
 export interface UsePickerValueContextValue {
+  /**
+   * Sets the current opening status of the picker.
+   * ```ts
+   * setOpen(true); // Opens the picker.
+   * setOpen(false); // Closes the picker.
+   * setOpen((prevOpen) => !prevOpen); // Toggles the opening status.
+   * ```
+   * @param {React.SetStateAction<boolean>} action The new opening status of the picker, it can be a function that will receive the previous opening status.
+   */
   setOpen: React.Dispatch<React.SetStateAction<boolean>>;
   /**
    * `true` if the picker is open, `false` otherwise.
diff --git a/packages/x-date-pickers/src/internals/models/props/basePickerProps.tsx b/packages/x-date-pickers/src/internals/models/props/basePickerProps.tsx
index c4fef0bdaa15..6af60cd19603 100644
--- a/packages/x-date-pickers/src/internals/models/props/basePickerProps.tsx
+++ b/packages/x-date-pickers/src/internals/models/props/basePickerProps.tsx
@@ -81,3 +81,15 @@ export interface BaseNonRangeNonStaticPickerProps {
    */
   name?: string;
 }
+
+const Component = () => {
+  return (
+    <div
+      onKeyDown={(event) => {
+        if (event.key === 'Escape') {
+          pickerContextValue.onClose();
+        }
+      }}
+    />
+  );
+};