Docs(web,web-twig,web-react): Migration Guides cleanup #DS-1250

lmc-eu · Jun 7, 2024 · c5b2996 · c5b2996
1 parent 6f1e000
commit c5b2996
Show file tree

Hide file tree

Showing 3 changed files with 84 additions and 54 deletions.
diff --git a/docs/migrations/web-react/MIGRATION-v2.md b/docs/migrations/web-react/MIGRATION-v2.md
@@ -1,21 +1,24 @@
-# Migration Guide WIP
+# Migration Guide
 
 Introducing version 2 of the _spirit-web-react_ package
 
 > Please follow these steps to safely upgrade to Spirit Design System v2 components.
 
+> ℹ️ Don't forget to check the [migration guide of the _spirit-web_ package][migration-guide-web] for general changes in
+> available feature flags, CSS, and other changes that might affect your project.
+
 ## Overview
 
 - [General Changes](#general-changes)
   - [Dropped Support for Node.js 16](#dropped-support-for-node-js-16)
   - [Form Components Required `id` Prop](#form-components-required-id-prop)
-  - [Placements in Tooltip and Dropdown](#placements-in-tooltip-and-dropdown)
+  - [Placement in Dropdown and Tooltip](#placement-in-tooltip-and-dropdown)
   - [The `id` Prop in Dropdown and Collapse](#the-id-prop-in-dropdown-and-collapse)
 - [Component Changes](#component-changes)
   - [Alert: `danger` Icon](#alert-danger-icon)
   - [Alert: `role="alert"`](#alert-rolealert)
   - [FileUploader: FileUploaderAttachment `buttonLabel` and `editButtonLabel` Props](#fileuploader-fileuploaderattachment-buttonlabel-and-editbuttonlabel-props)
-  - [Dropdown: Refactored](#dropdown-refactored)
+  - [Dropdown: New Structure](#dropdown-new-structure)
   - [Grid: Breakpoint Props](#grid-breakpoint-props)
   - [Grid: GridSpan Component](#grid-gridspan-component)
   - [Header: HeaderDesktopActions `isAtEnd` prop](#header-headerdesktopactions-isatend-prop)
@@ -26,7 +29,7 @@ Introducing version 2 of the _spirit-web-react_ package
   - [Tabs: TabItem and TabPane Props](#tabs-tabitem-and-tabpane-props)
   - [TextField: `label` prop](#textfield-label-prop)
   - [Tooltip: `off` Placement](#tooltip-off-placement)
-  - [Tooltip: Refactored](#tooltip-refactored)
+  - [Tooltip: New Structure](#tooltip-new-structure)
   - [TooltipModern](#tooltipmodern)
 
 ## General Changes
@@ -53,7 +56,7 @@ Affected components:
 
 Add `id` prop to the form components.
 
-### Placements in Tooltip and Dropdown
+### Placement in Dropdown and Tooltip
 
 The `Tooltip` and `Dropdown` components no longer support non-flow-relative placements.
 
@@ -145,7 +148,7 @@ Or manually replace the props in your project.
 - `<FileUploaderAttachment buttonLabel="Remove this attachment" … />` → `<FileUploaderAttachment removeText="Remove this attachment" … />`
 - `<FileUploaderAttachment editButtonLabel="Edit this attachment" … />` → `<FileUploaderAttachment editText="Edit this attachment" … />`
 
-### Dropdown: Refactored
+### Dropdown: New Structure
 
 The `Dropdown` component was refactored and new structure and API were introduced.
 
@@ -384,7 +387,7 @@ The `off` placement was removed.
 
 Please use the new refactored `Tooltip` component.
 
-### Tooltip: Refactored
+### Tooltip: New Structure
 
 The `Tooltip` component was refactored and new structure and API were introduced.
 
@@ -434,6 +437,7 @@ Or manually rename `TooltipModern` to the `Tooltip`.
 
 Please refer back to these instructions or reach out to our team if you encounter any issues during migration.
 
+[migration-guide-web]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/migrations/web/MIGRATION-v2.md
 [alert-role-documentation]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role
 [readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#additional-attributes
 [readme-codemods]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/codemods/README.md

diff --git a/docs/migrations/web-twig/MIGRATION-v3.md b/docs/migrations/web-twig/MIGRATION-v3.md
@@ -1,21 +1,24 @@
-# Migration Guide WIP
+# Migration Guide
 
 Introducing version 3 of the _spirit-web-twig_ package
 
 > Please follow these steps to safely upgrade to Spirit Design System v3 components.
 
+> ℹ️ Don't forget to check the [migration guide of the _spirit-web_ package][migration-guide-web] for general changes in
+> feature flags, CSS, JavaScript plugins, and other changes that might affect your project.
+
 ## Overview
 
 - [General Changes](#general-changes)
   - [Dropped Support for PHP 7.4](#dropped-support-for-php-74)
   - [Form Components Required `id` Prop](#form-components-required-id-prop)
-  - [Placements in Tooltip and Dropdown](#placements-in-tooltip-and-dropdown)
+  - [Placement in Dropdown and Tooltip](#placement-in-dropdown-and-tooltip)
 - [Component Changes](#component-changes)
   - [Alert: `danger` Icon](#alert-danger-icon)
   - [Alert: `role="alert"`](#alert-rolealert)
   - [Breadcrumbs: `goBackTitle` Prop](#breadcrumbs-gobacktitle-prop)
   - [Dropdown: `id` Prop](#dropdown-id-prop)
-  - [Dropdown: Components Naming](#dropdown-components-naming)
+  - [Dropdown: New Structure](#dropdown-new-structure)
   - [Grid: Breakpoint Props](#grid-breakpoint-props)
   - [Grid: GridSpan Component](#grid-gridspan-component)
   - [Header: Abstracts Class and Style](#header-abstracts-class-and-style)
@@ -24,7 +27,7 @@ Introducing version 3 of the _spirit-web-twig_ package
   - [Modal: ModalDialog Custom Height](#modal-modaldialog-custom-height)
   - [Modal: ModalDialog Uniform Appearance](#modal-modaldialog-uniform-appearance)
   - [Tabs: TabLink `target` Prop](#tabs-tablink-target-prop)
-  - [Tooltip: Composition](#tooltip-composition)
+  - [Tooltip: New Structure](#tooltip-new-structure)
   - [Tooltip: Hidden by default](#tooltip-hidden-by-default)
   - [Tooltip: TooltipPopover `enableControlledPlacement` Prop](#tooltip-tooltippopover-enablecontrolledplacement-prop)
   - [Tooltip: TooltipPopover Default Values](#tooltip-tooltippopover-default-values)
@@ -51,7 +54,7 @@ Affected components:
 
 Add `id` prop to the form components.
 
-### Placements in Tooltip and Dropdown
+### Placement in Dropdown and Tooltip
 
 The `Tooltip` and `Dropdown` components no longer support non-flow-relative placements.
 
@@ -121,7 +124,7 @@ The `id` prop is mandatory for the `Dropdown` component.
 
 Add `id` prop to the `Dropdown` component.
 
-### Dropdown: Components Naming
+### Dropdown: New Structure
 
 In order to have the root component called `Dropdown`, we renamed
 the `DropdownWrapper` component to `Dropdown` and the original
@@ -254,7 +257,7 @@ The reason for this change is to avoid confusion with the
 
 Replace `target` with `targetPaneId` in the `TabLink` component.
 
-### Tooltip: Composition
+### Tooltip: New Structure
 
 The `Tooltip` component structure was changed, so `Tooltip` (formerly the optional
 `TooltipWrapper`) is now a mandatory wrapping component. Similarly, `Tooltip` (the tip
@@ -406,6 +409,7 @@ See [`Tooltip` documentation][tooltip-readme] for more details and examples.
 
 Please refer back to this guide or reach out to our team if you encounter any issues during migration.
 
+[migration-guide-web]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/migrations/web/MIGRATION-v2.md
 [alert-role-documentation]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role
 [dictionary-placement]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#placement
 [dropdown-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/Dropdown/README.md

diff --git a/docs/migrations/web/MIGRATION-v2.md b/docs/migrations/web/MIGRATION-v2.md
@@ -1,4 +1,4 @@
-# Migration Guide WIP
+# Migration Guide
 
 Introducing version 2 of the _spirit-web_ package
 
@@ -9,18 +9,21 @@ Introducing version 2 of the _spirit-web_ package
 - [General Changes](#general-changes)
   - [Dropped Support for Node.js 16](#dropped-support-for-node-js-16)
   - [CSS Variables Component Prefix](#css-variables-component-prefix)
-  - [Placement in Tooltip and Dropdown](#placement-in-tooltip-and-dropdown)
-- [Component Changes](#component-changes)
+  - [Placement in Dropdown and Tooltip](#placement-in-dropdown-and-tooltip)
+- [Feature Flags](#feature-flags)
   - [Alert: Bordered Feature Flag](#alert-bordered-feature-flag)
-  - [Dropdown: Classes](#dropdown-classes)
-  - [Dropdown: Combined Placements](#dropdown-combined-placements)
   - [Dropdown: Shadow Feature Flag](#dropdown-shadow-feature-flag)
+  - [Modal: Uniform Variant Feature Flag](#modal-uniform-variant-feature-flag)
+- [JavaScript Plugins](#javascript-plugins)
+  - [Tooltip: Floating UI only](#tooltip-floating-ui-only)
+- [Component Changes](#component-changes)
+  - [Dropdown: New Structure](#dropdown-new-structure)
+  - [Dropdown: Combined Placements](#dropdown-combined-placements)
   - [Header: HeaderDesktopActions Alignment](#header-headerdesktopactions-alignment)
   - [Modal: (Non)Scrollable](#modal-nonscrollable)
   - [Modal: Custom Height](#modal-custom-height)
-  - [Modal: Uniform Variant Feature Flag](#modal-uniform-variant-feature-flag)
   - [Grid: GridSpan Component](#grid-gridspan-component)
-  - [Tooltip: FloatingUI only](#tooltip-floatingui-only)
+  - [Tooltip: New Structure](#tooltip-new-structure)
 
 ## General Changes
 
@@ -44,7 +47,7 @@ Update the CSS variables in your project to use the new component name prefix.
 - `--lines` → `--text-truncate-lines`
 - `--angle` → `--gradient-angle`
 
-### Placement in Tooltip and Dropdown
+### Placement in Dropdown and Tooltip
 
 The `Tooltip` and `Dropdown` components no longer support non-flow-relative placements.
 
@@ -81,7 +84,7 @@ See [Placement dictionary][dictionary-placement] for more details.
 - `.Dropdown--left` → `data-spirit-placement="left"`
 - `.Dropdown--leftTop` → `data-spirit-placement="left-start"`
 
-## Component Changes
+## Feature Flags
 
 ### Alert: Bordered Feature Flag
 
@@ -93,7 +96,54 @@ is the default.
 You can now safely delete the CSS class `.spirit-feature-alert-enable-bordered` and/or the Sass variable
 `$alert-enable-bordered` from your project as they have no effect.
 
-### Dropdown: Classes
+### Dropdown: Shadow Feature Flag
+
+The feature flag enabling the dropdown shadow was removed and the enhanced
+shadow is the default.
+
+#### Migration Guide
+
+You can now safely delete the CSS class `.spirit-feature-dropdown-enable-enhanced-shadow` and/or the Sass variable
+`$dropdown-enable-enhanced-shadow` from your project as they have no effect.
+
+### Modal: Uniform Variant Feature Flag
+
+The feature flag enabling the uniform variant of modal was removed and the
+uniform variant is the default.
+
+#### Migration Guide
+
+You can now safely delete the CSS class `.spirit-feature-modal-enable-uniform-dialog` and/or the Sass variable
+`$modal-enable-uniform-dialog` from your project as they have no effect.
+
+### Tooltip: Controlled Placement Feature Flag
+
+The feature flag enabling the data-selector-controlled placement (`data-spirit-placement-controlled`) for the tooltip
+was removed. The controlled placement is the default.
+
+#### Migration Guide
+
+You can now safely delete the CSS class `.spirit-feature-tooltip-enable-data-placement` and/or the Sass variable
+`$tooltip-enable-data-placement` from your project as they have no effect.
+
+## JavaScript Plugins
+
+### Tooltip: Floating UI only
+
+Non-Floating-UI and CSS-only Tooltips are no longer supported. The Tooltip component is now dependent on the Floating UI library and has a new structure.
+See the updated [Tooltip Readme][readme-tooltip] for more details on how to use Tooltip now.
+
+#### Migration Guide
+
+Delete the [controlled placement feature flag](#tooltip-controlled-placement-feature-flag) and follow the
+[new Tooltip structure](#tooltip-new-structure).
+
+## Component Changes
+
+> ℹ️ Do you use the _spirit-web-react_ or _spirit-web-twig_ package? You are done here! 🎉
+> Please refer to the respective migration guide for the changes in the React or Twig components.
+
+### Dropdown: New Structure
 
 In order to have the root element called `Dropdown` we renamed the `DropdownWrapper`
 component to `Dropdown` and the original `Dropdown` component to `DropdownPopover`.
@@ -120,16 +170,6 @@ Instead of using `.Dropdown--bottom.Dropdown--left`, use combination `bottom-sta
 - `.Dropdown--right.Dropdown--top` → `data-spirit-placement="right-start"`
 - `.Dropdown--right.Dropdown--bottom` → `data-spirit-placement="right-end"`
 
-### Dropdown: Shadow Feature Flag
-
-The feature flag enabling the dropdown shadow was removed and the enhanced
-shadow is the default.
-
-#### Migration Guide
-
-You can now safely delete the CSS class `.spirit-feature-dropdown-enable-enhanced-shadow` and/or the Sass variable
-`$dropdown-enable-enhanced-shadow` from your project as they have no effect.
-
 ### Header: HeaderDesktopActions Alignment
 
 The `HeaderDesktopActions` component slots were simplified and the second slot alignment is now
@@ -170,16 +210,6 @@ Update the custom properties in your project to use the new names:
 - `--modal-preferred-height-tablet` → `--modal-dialog-height-tablet`
 - `--modal-max-height-tablet` → `--modal-dialog-max-height-tablet`
 
-### Modal: Uniform Variant Feature Flag
-
-The feature flag enabling the uniform variant of modal was removed and the
-uniform variant is the default.
-
-#### Migration Guide
-
-You can now safely delete the CSS class `.spirit-feature-modal-enable-uniform-dialog` and/or the Sass variable
-`$modal-enable-uniform-dialog` from your project as they have no effect.
-
 ### Grid: GridSpan Component
 
 The `GridSpan` component was removed and the `GridItem` component should be used instead.
@@ -201,17 +231,9 @@ The `GridSpan` component was removed and the `GridItem` component should be used
   - `column-start` = 1 + (12 - 6) / 2 = 4
   - `column-start` = 1 + (12 - 4) / 2 = 5
 
-### Tooltip: FloatingUI only
-
-Non-FloatingUI and CSS-only Tooltips are no longer supported. The Tooltip component is now dependent on the FloatingUI library and has a new structure.
-See the updated [Tooltip Readme][readme-tooltip] for more details on how to use Tooltip now.
-The feature flag enabling the data-selector-controlled placement (`data-spirit-placement-controlled`) for the tooltip was removed.
-
-#### Migration Guide
+### Tooltip: New Structure
 
-You can now safely delete the CSS class `.spirit-feature-tooltip-enable-data-placement` and/or the Sass variable
-`$tooltip-enable-data-placement` from your project as they have no effect.
-Please follow new Tooltip structure.
+TODO
 
 ---