docs: improve and extend upgrade guide for v11

Author: balzss

docs/contributor-docs/upgrade-guide.md

@@ -8,35 +8,42 @@ order: 7
 
 ## InstUI and React
 
-> React 16 support was dropped with InstUI 11. Please upgrade to React 17 or later before upgrading to InstUI v11!
+> React 16 support was dropped with InstUI 11. Please upgrade to **React 18 or later** before upgrading to InstUI v11!
 
 ### React 19
 
-InstUI v11 added support for React 19. But upgrading to React 19 might cause issues because InstUI needs to access the native DOM in some cases and React introduced a breaking change here by [removing `ReactDOM.findDOMNode()`](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#removed-reactdom-finddomnode). If you are upgrading to React 19, you will need to add `ref`s to some of your custom components that use InstUI utilities, see [this guide](/#accessing-the-dom). We suggest to check your code thoroughly for errors, especially places where you use your own components as some kind of popovers or its triggers (e.g. Menu, Popover, Tooltip, Drilldown,..)
+InstUI v11 added support for React 19. But upgrading to React 19 might cause issues because InstUI needs to access the native DOM in some cases and React introduced a breaking change here by [removing `ReactDOM.findDOMNode()`](<https://www.google.com/search?q=%5Bhttps://react.dev/blog/2024/04/25/react-19-upgrade-guide%23removed-reactdom-finddomnode%5D(https://react.dev/blog/2024/04/25/react-19-upgrade-guide%23removed-reactdom-finddomnode)>). If you are upgrading to React 19, you will need to add `ref`s to some of your custom components that use InstUI utilities, see [this guide](https://www.google.com/search?q=/%23accessing-the-dom). We suggest to check your code thoroughly for errors, especially places where you use your own components as some kind of popovers or its triggers (e.g. Menu, Popover, Tooltip, Drilldown,..).
 
-If you are staying on React 17 or 18 you might just see error messages like (`Error: ${elName} doesn't have "ref" property.`), but your code should work the same as with InstUI v10.
+If you are using React 18 you might just see error messages like (`Error: ${elName} doesn't have "ref" property.`), but your code should work the same as with InstUI v10.
 
-## Removal of deprecated props/components/APIs
+---
 
-### InstUISettingsProvider
+## PropTypes Support Dropped
 
-[InstUISettingsProvider](/#InstUISettingsProvider)'s `as` prop was removed, it will always render as a `<span>` (note: it will only render anything to the DOM if you provide a value to the `dir` prop.). The provided codemod will remove this prop automatically (see below).
+With React 19, support for **PropTypes was dropped** from the core library. While it's still possible to use them with third-party libraries, InstUI has decided to no longer support them based on user feedback.
 
-### Table
+**Tip:** To see how the removal of `propTypes` might affect your application's business logic, you can use a Babel plugin like **`babel-plugin-transform-react-remove-prop-types`** to strip them out during your build process for testing.
 
-[Table](/#Table) is now using [TableContext](#TableContext) to pass down data to its child components, the following props are no longer passed down to their children (This should only affect you if you wild custom table rows or cells):
+---
 
-| Component | prop        | Substitute / Notes              |
-| --------- | ----------- | ------------------------------- |
-| `Row`     | `isStacked` | is now stored in `TableContext` |
-| `Body`    | `isStacked` | is now stored in `TableContext` |
-| `Body`    | `hover`     | is now stored in `TableContext` |
-| `Body`    | `headers`   | is now stored in `TableContext` |
+## Changes to Testability
+
+The **`@testable` decorator has been removed**. The `data-cid` props, which were previously added by this decorator in development builds, are now **always added to components**. This change was made in response to frequent requests for a consistent way to identify InstUI components for end-to-end (e2e) tests.
+
+As a result of this change, the **`ALWAYS_APPEND_UI_TESTABLE_LOCATORS`** Node.js environment variable is no longer used.
+
+---
+
+## Removal of deprecated props/components/APIs
+
+### InstUISettingsProvider
+
+[InstUISettingsProvider](https://www.google.com/search?q=/%23InstUISettingsProvider)'s `as` prop was removed, it will always render as a `<span>` (note: it will only render anything to the DOM if you provide a value to the `dir` prop.). The provided codemod will remove this prop automatically (see below).
 
 ### Theming engine changes
 
 | Removed                                            | What to use instead?                                                                                  |
-| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| :------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
 | `canvas.use()`, `canvasHighContrast.use()`         | Wrap all your application roots in `<InstUISettingsProvider>`                                         |
 | `canvasThemeLocal`, `canvasHighContrastThemeLocal` | Use `canvas` and `canvasHighContrast` respectively, they are the same objects.                        |
 | `variables` field on theme objects                 | Use `canvas.borders` instead of `canvas.variables.borders` (same for all other fields)                |
@@ -48,10 +55,36 @@ We have removed these utilities from the `ui-react-utils` package because we are
 
 If you want to still use these we suggest to copy-paste their code from the latest v10 codebase (Note: they only work for class-based components!).
 
+---
+
+## Component Changes
+
+### CodeEditor
+
+The **`<CodeEditor>` component** from the `ui-code-editor` package has been **removed** due to significant accessibility issues. Please use the **`<SourceCodeEditor>`** component as a replacement.
+
+### Table
+
+[Table](https://www.google.com/search?q=/%23Table) is now using [TableContext](https://www.google.com/search?q=%23TableContext) to pass down data to its child components, the following props are no longer passed down to their children (This should only affect you if you have custom table rows or cells):
+
+| Component | prop        | Substitute / Notes              |
+| :-------- | :---------- | :------------------------------ |
+| `Row`     | `isStacked` | is now stored in `TableContext` |
+| `Body`    | `isStacked` | is now stored in `TableContext` |
+| `Body`    | `hover`     | is now stored in `TableContext` |
+| `Body`    | `headers`   | is now stored in `TableContext` |
+
+### Tag
+
+The **`maxWidth` theme variable has been removed** from the `Tag` component. As a result, **`<Tag>` can no longer be truncated**. This change was made because placing a tooltip on a non-interactive element is an accessibility anti-pattern. You will need to handle truncation and tooltips via a new design if this functionality is required.
+
+---
+
 ## API Changes
 
-- `ui-dom-utils`/`getComputedStyle` can now return `undefined`: In previous versions sometimes returned an empty object which could lead to runtime exceptions when one tried to call methods of `CSSStyleDeclaration` on it.
-- TO-DO: [TimeSelect](/#TimeSelect) as a controlled component can now return an '' instead of a valid date when its input field is cleared. In previous versions it always reverted to the last selected value when the input field was cleared and lost focus.
+- `ui-dom-utils`/`getComputedStyle` can now return `undefined`: In previous versions it sometimes returned an empty object which could lead to runtime exceptions when one tried to call methods of `CSSStyleDeclaration` on it.
+
+---
 
 ## Codemods