Docs(web): List Deprecations in the web package #DS-1043

packages/web/DEPRECATIONS-v2.md

@@ -0,0 +1,120 @@
+# Deprecations List
+
+Following deprecations and feature flags will be removed in version 2 of the _spirit-web_ package.
+
+> Please follow these steps to safely upgrade your design system to Spirit Design System v2 components.
+
+[What are deprecations?][readme-deprecations]
+
+[What are feature flags?][readme-feature-flags]
+
+## Feature Flags
+
+### Dropdown Shadow
+
+The feature flag enabling the dropdown shadow will be removed and the enhanced
+shadow will be enabled by default.
+
+### Modal Uniform Variant
+
+The feature flag enabling the uniform variant of modal will be removed and the
+uniform variant will be enabled by default.
+
+### Tooltip Data Selector Controlled Placement
+
+The feature flag enabling the data selector controlled placement (`data-spirit-placement-controlled`)
+for tooltip will be removed and the data selector controlled placement will be enabled by default.
+
+## Deprecations
+
+### Dropdown Combined Placements
+
+Combined placement classes for dropdown will be removed.
+
+#### Migration Guide
+
+Instead of using `.Dropdown--bottom.Dropdown--left`, use `.Dropdown--bottomLeft` and so on.
+
+- `.Dropdown--top.Dropdown--left` → `.Dropdown--topLeft`
+- `.Dropdown--top.Dropdown--right` → `.Dropdown--topRight`
+- `.Dropdown--bottom.Dropdown--left` → `.Dropdown--bottomLeft`
+- `.Dropdown--bottom.Dropdown--right` → `.Dropdown--bottomRight`
+- `.Dropdown--left.Dropdown--top` → `.Dropdown--leftTop`
+- `.Dropdown--left.Dropdown--bottom` → `.Dropdown--leftBottom`
+- `.Dropdown--right.Dropdown--top` → `.Dropdown--rightTop`
+- `.Dropdown--right.Dropdown--bottom` → `.Dropdown--rightBottom`
+
+### Tooltip and Dropdown Placement Classes
+
+Placement classes for Tooltip and Dropdown will be removed.
+
+#### Migration Guide
+
+Instead of using `Tooltip--top` or `Tooltip--topLeft` or `Dropdown--top` or `Dropdown--topLeft`,
+use data attribute like`data-spirit-placement="top"` or `data-spirit-placement="top-start"`.
+
+- `.Tooltip--top` → `data-spirit-placement="top"`
+- `.Tooltip--topRight` → `data-spirit-placement="top-right"`
+- `.Tooltip--topLeft` → `data-spirit-placement="top-start"`
+- `.Tooltip--right` → `data-spirit-placement="right"`
+- `.Tooltip--rightTop` → `data-spirit-placement="right-top"`
+- `.Tooltip--rightBottom` → `data-spirit-placement="right-bottom"`
+- `.Tooltip--bottom` → `data-spirit-placement="bottom"`
+- `.Tooltip--bottomRight` → `data-spirit-placement="bottom-right"`
+- `.Tooltip--bottomLeft` → `data-spirit-placement="bottom-start"`
+- `.Tooltip--left` → `data-spirit-placement="left"`
+- `.Tooltip--leftTop` → `data-spirit-placement="left-top"`
+- `.Tooltip--leftBottom` → `data-spirit-placement="left-bottom"`
+- `.Dropdown--top` → `data-spirit-placement="top"`
+- `.Dropdown--topRight` → `data-spirit-placement="top-right"`
+- `.Dropdown--topLeft` → `data-spirit-placement="top-start"`
+- `.Dropdown--right` → `data-spirit-placement="right"`
+- `.Dropdown--rightTop` → `data-spirit-placement="right-top"`
+- `.Dropdown--rightBottom` → `data-spirit-placement="right-bottom"`
+- `.Dropdown--bottom` → `data-spirit-placement="bottom"`
+- `.Dropdown--bottomRight` → `data-spirit-placement="bottom-right"`
+- `.Dropdown--bottomLeft` → `data-spirit-placement="bottom-start"`
+- `.Dropdown--left` → `data-spirit-placement="left"`
+- `.Dropdown--leftTop` → `data-spirit-placement="left-top"`
+- `.Dropdown--leftBottom` → `data-spirit-placement="left-bottom"`
+
+### Tooltip and Dropdown Placements
+
+The `Tooltip` and `Dropdown` components will no longer support non-flows placements.
+
+#### Migration Guide
+
+Instead of using `Tooltip--topLeft` or `Dropdown--topLeft`, use data attribute value like
+`data-spirit-placement="top-start"` and so on. See [Placement dictionary][dictionary-placement]
+for more details.
+
+- `.Tooltip--topLeft` → `data-spirit-placement="top-start"`
+- `.Tooltip--topRight` → `data-spirit-placement="top-end"`
+- `.Tooltip--bottomLeft` → `data-spirit-placement="bottom-start"`
+- `.Tooltip--bottomRight` → `data-spirit-placement="bottom-end"`
+- `.Tooltip--leftTop` → `data-spirit-placement="left-start"`
+- `.Tooltip--leftBottom` → `data-spirit-placement="left-end"`
+- `.Tooltip--rightTop` → `data-spirit-placement="right-start"`
+- `.Tooltip--rightBottom` → `data-spirit-placement="right-end"`
+- `.Dropdown--topLeft` → `data-spirit-placement="top-start"`
+- `.Dropdown--topRight` → `data-spirit-placement="top-end"`
+- `.Dropdown--bottomLeft` → `data-spirit-placement="bottom-start"`
+- `.Dropdown--bottomRight` → `data-spirit-placement="bottom-end"`
+- `.Dropdown--leftTop` → `data-spirit-placement="left-start"`
+- `.Dropdown--leftBottom` → `data-spirit-placement="left-end"`
+- `.Dropdown--rightTop` → `data-spirit-placement="right-start"`
+- `.Dropdown--rightBottom` → `data-spirit-placement="right-end"`
+
+### Modal (Non)Scrollable
+
+The `.ModalDialog--nonScrollable` modifier will be removed and the ModalDialog will be made non-scrollable by default.
+
+#### Migration Guide
+
+In a new version, to make the ModalDialog scrollable, use the `.ModalDialog--scrollable` modifier class.
+
+- `.ModalDialog` → `.ModalDialog .ModalDialog--scrollable`
+
+[readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md#deprecations
+[readme-feature-flags]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md#feature-flags
+[dictionary-placement]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#placement