From d69dd88b25720815a1082aee72ebda9666e50044 Mon Sep 17 00:00:00 2001
From: Daniel Sil <daniel.sil@kiwi.com>
Date: Tue, 11 Feb 2025 17:06:32 +0100
Subject: [PATCH] docs: add Modal BC to migration guide

---
 .../04-migration-guides/01-v20.mdx            | 75 +++++++++++++++----
 1 file changed, 60 insertions(+), 15 deletions(-)

diff --git a/docs/src/documentation/05-development/04-migration-guides/01-v20.mdx b/docs/src/documentation/05-development/04-migration-guides/01-v20.mdx
index 4d138986d4..7c237b37a9 100644
--- a/docs/src/documentation/05-development/04-migration-guides/01-v20.mdx
+++ b/docs/src/documentation/05-development/04-migration-guides/01-v20.mdx
@@ -12,6 +12,28 @@ With this guide, we aim to walk through all the breaking changes and how they ca
 
 ## Breaking changes
 
+### Badge component removed the `border` prop
+
+The `Badge` component removed the `border` prop, as it was not being used internally.
+
+Please adapt your code to remove the `border` prop. No visual changes are expected.
+
+**Before:**
+
+```jsx
+import Badge from "@kiwicom/orbit-components/lib/Badge";
+
+<Badge border={false} />;
+```
+
+**Now:**
+
+```jsx
+import Badge from "@kiwicom/orbit-components/lib/Badge";
+
+<Badge />;
+```
+
 ### Required props in HorizontalScroll if `arrows` is true
 
 The `HorizontalScroll` component now requires `arrowLeftAriaLabel` and `arrowRightAriaLabel` props if `arrows` is true.
@@ -50,34 +72,57 @@ intl.formatMessage({
 });
 ```
 
-To run the codemod, use the following command:
-
-```bash
-npx jscodeshift -t https://raw.githubusercontent.com/kiwicom/orbit/master/packages/orbit-components/transforms/horizontalscroll-aria-labels.js --parser=tsx --extensions=ts,tsx <pathToYourCode>
-```
-
-Make sure to run prettier after running the codemod, as it might introduce some formatting changes.
-
 Feel free to customize the translations according to your needs, but please maintain the same translation key structure (`common.screenreader.*`) when requesting translations.
 
-### Badge component removed the `border` prop
+### Required prop in Modal if `onClose` is defined and `hasCloseButton` is explicitly false
 
-The `Badge` component removed the `border` prop, as it was not being used internally.
+The `Modal` component used to have a default value for the prop `labelClose`. We removed this default value, so now you need to provide it.
+This prop is also now required if `onClose` is defined and `hasCloseButton` is explicitly set to `false` (the default value of `hasCloseButton` prop is still `true`, as it has been).
 
-Please adapt your code to remove the `border` prop. No visual changes are expected.
+This `labelClose` prop provides the label for the close button that is applied to the `Modal` so that assistive technologies can announce it correctly, given that it renders a button with just an icon.
 
 **Before:**
 
 ```jsx
-import Badge from "@kiwicom/orbit-components/lib/Badge";
+import Modal from "@kiwicom/orbit-components/lib/Modal";
 
-<Badge border={false} />;
+<Modal onClose={handleClose} />;
 ```
 
+The `labelClose` prop has a default value of `"Close"`. Notice that the `hasCloseButton` prop is undefined, so by default it is set to `true`.
+
 **Now:**
 
 ```jsx
-import Badge from "@kiwicom/orbit-components/lib/Badge";
+import Modal from "@kiwicom/orbit-components/lib/Modal";
 
-<Badge />;
+<Modal onClose={handleClose} labelClose="Close" />;
+```
+
+Make sure to provide translated strings for the `labelClose` prop.
+
+To ease the migration, we provide a codemod to help you out, with some default generic translations.
+The codemod will inject `intl.formatMessage` calls with the default translations, in this case:
+
+```jsx
+intl.formatMessage({
+  id: "orbit.button_close",
+  defaultMessage: "Close",
+});
+```
+
+Feel free to customize the translations according to your needs, by eventually providing more context to the modal it refers to.
+
+## Codemod
+
+A codemod is available to help with the migration. It should target the new props that require (translated) strings.
+Please note that the codemod **does not** guarantee a full migration, nor its complete correctness.
+Manual checks are still necessary, especially if some props are being calculated conditionally or the components are imported with different names.
+
+To run the codemod, use the following command:
+
+```bash
+npx jscodeshift -t https://raw.githubusercontent.com/kiwicom/orbit/master/packages/orbit-components/transforms/aria-labels.js --parser=tsx --extensions=ts,tsx <pathToYourCode>
 ```
+
+Make sure to run prettier after running the codemod, as it might introduce some formatting changes.