diff --git a/packages/web/DEPRECATIONS-v2.md b/packages/web/DEPRECATIONS-v2.md new file mode 100644 index 0000000000..87eb7f6dd4 --- /dev/null +++ b/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