From d99ac8e8e4ae0c78fc9bbc1ade7cc6b68b1b4f97 Mon Sep 17 00:00:00 2001 From: Adam Kudrna Date: Fri, 7 Jun 2024 10:10:08 +0200 Subject: [PATCH] Docs(web,web-twig,web-react): Migration Guides cleanup #DS-1250 --- docs/migrations/web-react/MIGRATION-v2.md | 414 ++++++++++++++-------- docs/migrations/web-twig/MIGRATION-v3.md | 260 ++++++++------ docs/migrations/web/MIGRATION-v2.md | 290 ++++++++++----- 3 files changed, 608 insertions(+), 356 deletions(-) diff --git a/docs/migrations/web-react/MIGRATION-v2.md b/docs/migrations/web-react/MIGRATION-v2.md index aaf5331fa3..2d7eb939ee 100644 --- a/docs/migrations/web-react/MIGRATION-v2.md +++ b/docs/migrations/web-react/MIGRATION-v2.md @@ -1,21 +1,26 @@ -# Migration Guide WIP +# Migration Guide -Introducing version 2 of the _spirit-web-react_ package +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) - - [The `id` Prop in Dropdown and Collapse](#the-id-prop-in-dropdown-and-collapse) + - [Dropped Support for Node.js 16](#dropped-support-for-nodejs-16) + - [Required `id` Prop in Form Components](#required-id-prop-in-form-components) + - [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) + - [Collapse: `id` Prop](#collapse-id-prop) + - [Dropdown: New Structure](#dropdown-new-structure) + - [Dropdown: `id` Prop](#dropdown-id-prop) + - [Dropdown: Placement Control](#dropdown-placement-control) - [FileUploader: FileUploaderAttachment `buttonLabel` and `editButtonLabel` Props](#fileuploader-fileuploaderattachment-buttonlabel-and-editbuttonlabel-props) - - [Dropdown: Refactored](#dropdown-refactored) - [Grid: Breakpoint Props](#grid-breakpoint-props) - [Grid: GridSpan Component](#grid-gridspan-component) - [Header: HeaderDesktopActions `isAtEnd` prop](#header-headerdesktopactions-isatend-prop) @@ -24,9 +29,10 @@ Introducing version 2 of the _spirit-web-react_ package - [Modal: ModalDialog Custom Height](#modal-modaldialog-custom-height) - [Modal: ModalDialog Uniform Appearance](#modal-modaldialog-uniform-appearance) - [Tabs: TabItem and TabPane Props](#tabs-tabitem-and-tabpane-props) - - [TextField: `label` prop](#textfield-label-prop) + - [TextField: `label` Prop](#textfield-label-prop) - [Tooltip: `off` Placement](#tooltip-off-placement) - - [Tooltip: Refactored](#tooltip-refactored) + - [Tooltip: New Structure](#tooltip-new-structure) + - [Tooltip: Placement Control](#tooltip-placement-control) - [TooltipModern](#tooltipmodern) ## General Changes @@ -35,124 +41,88 @@ Introducing version 2 of the _spirit-web-react_ package The Node.js v16 is no longer supported. The minimum required Node.js version is 18. -### Form Components Required `id` Prop +### Required `id` Prop in Form Components -The `id` prop is required for all form components. +The `id` prop is now consistently required by all form components. Affected components: -- `Checkbox` -- `FieldGroup` -- `FileUploader` -- `Radio` -- `Select` -- `TextArea` -- `TextField` +- Checkbox +- FieldGroup +- FileUploader +- Radio +- Select +- TextArea +- TextField #### Migration Guide -Add `id` prop to the form components. +Add the `id` prop to the listed form components. + +### Placement in Dropdown and Tooltip -### Placements in Tooltip and Dropdown +The Dropdown and Tooltip components now support only flow-relative cross-axis placements. -The `Tooltip` and `Dropdown` components no longer support non-flow-relative placements. +New [placement naming][dictionary-placement]: + +1. The main placement axis (top, right, bottom, left) remains the same. +2. The cross axis (formerly also top, right, bottom, left) is now relative to the main axis: start, end. #### Migration Guide -Use codemod to automatically update your codebase. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/dropdown-tooltip-flow-placement ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. -Or manually edit your usages of Tooltip and Dropdown. Instead of using `top-left` or -`left-bottom` and etc, use `top-start` or `left-end` and so on. -See [Placement dictionary][dictionary-placement] for more details. - -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` - -### The `id` Prop in Dropdown and Collapse - -The `id` prop are mandatory for the `Dropdown` and `Collapse` components. - -#### Migration Guide - -Add `id` prop to the `Dropdown` component. -Add `id` prop to the `Collapse` component. +🔧 Or check [Dropdown: Placement Control](#dropdown-placement-control) and +[Tooltip: Placement Control](#tooltip-placement-control) for manual migration steps. ## Component Changes ### Alert: `danger` Icon The `danger` icon for `danger` color in the Alert component is now required. -Please, add the `danger` icon to your project's assets. #### Migration Guide -Either install newer version of the `spirit-icons` package or add `danger` named icon to your project's icons. +Either install newer version of the _spirit-icons_ package, or add an icon named `danger` to your project's icons. ### Alert: `role="alert"` -The `role="alert"` has been removed from the default setting of the component. +The `role="alert"` was removed from the default setting of the component. -The alert role is used to communicate an important and usually time-sensitive message to the user. When this role is added to an element, -the browser will send out an accessible alert event to assistive technology products which can then notify the user. -The alert role should only be used for information that requires the user's immediate attention, which is typically -content that is dynamically displayed (such as form validation message etc.), not for content that appears on page load. -It should not be used on HTML that the user hasn't interacted with. +As explained in the [ARIA: alert role][alert-role-documentation] documentation: -For more information see [ARIA: alert role][alert-role-documentation]. +> The alert role is used to communicate an important and usually time-sensitive message to the user. When this role is +> added to an element, the browser will send out an accessible alert event to assistive technology products which can +> then notify the user. The alert role should only be used for information that requires the user's immediate attention, +> which is typically content that is dynamically displayed (such as form validation message etc.), not for content that +> appears on page load. It should not be used on HTML that the user hasn't interacted with. #### Migration Guide -In case you need to use the component as an information that requires the user's immediate attention, -you can use `role="alert"` as an [additional attribute][readme-additional-attributes]. +In case you need to use the component as an information that requires the user's immediate attention, you can use +`role="alert"` as an [additional attribute][readme-additional-attributes]. -### FileUploader: FileUploaderAttachment `buttonLabel` and `editButtonLabel` Props +### Collapse: `id` Prop -The `buttonLabel` and `editButtonLabel` props were removed from the `FileUploaderAttachment` component. -Use `removeText` and `editText` props instead. +The `id` prop is now required by the Collapse component. #### Migration Guide -Use codemod to automatically update your codebase: +Add the `id` prop to the Collapse component. -```sh -npx @lmc-eu/spirit-codemods -p -t v2/web-react/fileuploader-prop-names -``` - -See [Codemods documentation][readme-codemods] for more details. - -Or manually replace the props in your project. - -- `` → `` -- `` → `` - -### Dropdown: Refactored +### Dropdown: New Structure -The `Dropdown` component was refactored and new structure and API were introduced. +The Dropdown component was refactored and new structure and API were introduced. #### Migration Guide -See [`Dropdown` documentation][dropdown-readme] for more details and examples. -The new `Dropdown` has a different API. +The new Dropdown has a different API. Instead of: @@ -174,12 +144,73 @@ const onToggle = () => setIsOpen(!isOpen); ; ``` -If you are still using the `DropdownModern` component name instead of `Dropdown`, you can use codemode to automatically update your code. +👉 See [Dropdown documentation][dropdown-readme] for more details and examples. + +🪄 If you are still using the DropdownModern component instead of Dropdown, you can use codemod to automatically update +your code base: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/dropdownmodern-component-name ``` +👉 See [Codemods documentation][readme-codemods] for more details. + +### Dropdown: `id` Prop + +The `id` prop is now required by the Dropdown component. + +#### Migration Guide + +Add the `id` prop to the Dropdown component. + +### Dropdown: Placement Control + +The Dropdown component now supports only [flow-relative cross-axis placements](#placement-in-dropdown-and-tooltip). + +#### Migration Guide + +🪄 Use codemod described in [Placement in Dropdown and Tooltip](#placement-in-dropdown-and-tooltip) to automatically +update your codebase. + +
+ 🔧 Manual Migration Steps + +Manually update cross-axis names in the placement prop: + +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +
+ +### FileUploader: FileUploaderAttachment `buttonLabel` and `editButtonLabel` Props + +The `buttonLabel` and `editButtonLabel` props were removed from the FileUploaderAttachment component. +Use `removeText` and `editText` props instead. + +#### Migration Guide + +🪄 Use codemod to automatically update your codebase: + +```sh +npx @lmc-eu/spirit-codemods -p -t v2/web-react/fileuploader-prop-names +``` + +👉 See [Codemods documentation][readme-codemods] for more details. + +
+ 🔧 Manual Migration Steps + +Manually replace the props in your project: + +- `` → `` +- `` → `` +
+ ### Grid: Breakpoint Props The `cols` prop in the `Grid` now supports object values for different breakpoints. @@ -187,194 +218,239 @@ The `tablet` and `desktop` props were removed. #### Migration Guide -Use codemod to automatically update your codebase. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/grid-breakpoint-props ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. + +
+ 🔧 Manual Migration Steps -Or manually replace `tablet` and `desktop` props with the `cols` object prop. +Manually replace `tablet` and `desktop` props with the `cols` object prop. - `` → `` - `` → `` - `` → `` +
### Grid: GridSpan Component -The `GridSpan` component was removed. Use `GridItem` instead. +The GridSpan component was removed. Instead, you can use the more powerful GridItem component that allows you to define +the start and end columns for each breakpoint. #### Migration Guide -Use our codemod to automatically migrate your code. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/grid-gridspan ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. -Or follow these steps: +
+ 🔧 Manual Migration Steps The hardest part in the migration is to get the `columnStart` value. The equation is `1 + (columns - over) / 2`, -where `columns` is the number of columns in the grid and `over` is the value from the `GridSpan` component. +where `columns` is the number of columns in the grid and `over` is the value from the GridSpan component. The default number of columns is 12, so the equation is `1 + (12 - over) / 2` most of the time. 1. Replace `GridSpan` with `GridItem`. -2. Calculate and set the `columnStart` value as `1 + (columns - over) / 2`. In our 12-column grid, the equation is `1 + (12 - over) / 2`, where `over` is the value from the `GridSpan` component. +2. Calculate and set the `columnStart` value as `1 + (columns - over) / 2`. In our 12-column grid, the equation is `1 + (12 - over) / 2`, where `over` is the value from the GridSpan component. 3. Set the `columnEnd` value to `span over` or use `columnStart + over`. -4. If you use responsive props, calculate the values for each breakpoint and pass them to the `GridItem` component `columnStart` and `columnEnd` props as an object. +4. If you use responsive props, calculate the values for each breakpoint and pass them to the GridItem component `columnStart` and `columnEnd` props as an object. 5. Remove the `over` prop. -Examples: - -- `…` → `…` - - `columnStart` = 1 + (12 - 4) / 2 = 5 -- `…` → `…` - - `columnStart` = 1 + (12 - 6) / 2 = 4 -- `…` → `…` +##### Examples + +- Centered grid item over 4 columns: + ```diff + -… + +… + ``` + `columnStart` = 1 + (12 - 4) / 2 = 5 +- Centered grid item over 6 columns: + ```diff + -… + +… + ``` + `columnStart` = 1 + (12 - 6) / 2 = 4 +- Responsive grid item centered over 8 columns on mobile, 6 columns on tablet, and 4 columns on desktop: + ```diff + -… + +… + ``` - `columnStart` = 1 + (12 - 8) / 2 = 3 - `columnStart` = 1 + (12 - 6) / 2 = 4 - `columnStart` = 1 + (12 - 4) / 2 = 5 +
### Header: HeaderDesktopActions `isAtEnd` prop -The `HeaderDesktopActions` component slots were simplified and the second slot alignment is now -available by using the `isAtEnd` prop. +The HeaderDesktopActions component slots were simplified and the second slot alignment is now available by using the +`isAtEnd` prop. -The `HeaderDesktopActions` prop `color` was removed. +The HeaderDesktopActions `color` prop was removed. #### Migration Guide -Use our codemod to automatically migrate your code. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/header-headerdesktopactions-isatend ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. -Or follow these steps: +
+ 🔧 Manual Migration Steps -Use the `HeaderDesktopActions` with `isAtEnd` prop instead of the `color="secondary"` prop. -Remove the `color` prop from the `HeaderDesktopActions` component. +Use the HeaderDesktopActions component with the `isAtEnd` prop instead of the `color="secondary"` prop. +Remove the `color` prop from the HeaderDesktopActions component. - `` → `` - `` → `` +
### Modal: ModalDialog `isExpandedOnMobile` Prop -The `isExpandedOnMobile` prop is set to `true` by default and the ModalDialog is expanded on mobile -by default. It is possible to re-collapse the inside by setting the `isExpandedOnMobile` prop -to `false`. +The default value of the `isExpandedOnMobile` prop is now set to `true` and the ModalDialog is expanded on mobile by +default. It is possible to re-collapse the inside by setting the `isExpandedOnMobile` prop to `false`. #### Migration Guide -Use codemod to automatically update your codebase. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/modal-isexpandedonmobile-prop ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. + +
+ 🔧 Manual Migration Steps -Or manually add `isExpandedOnMobile={false}` prop to the `ModalDialog` component to keep the current behavior. +Manually add `isExpandedOnMobile={false}` prop to the ModalDialog component to keep the current behavior. + +
### Modal: ModalDialog `isScrollable` Prop -The `isScrollable` prop is now set to `false` by default and the ModalDialog is non-scrollable by default. +The default value of the `isScrollable` prop is now set to `false` and the ModalDialog is non-scrollable by default. It is possible to re-enable the inside scrolling by adding the `isScrollable` prop. #### Migration Guide -Use codemod to automatically update your codebase. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/modal-iscrollable-prop ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. + +
+ 🔧 Manual Migration Steps -Or manually add `isScrollable` prop to the `ModalDialog` component. +Manually add the `isScrollable` prop to the ModalDialog component. -If you use `ScrollView` for scrolling the content of your modal, you must also make the -`ModalDialog` scrollable by setting the `isScrollable` prop. +
+ +If you use ScrollView for scrolling the content of your modal, you must also make the ModalDialog scrollable by setting +the `isScrollable` prop. ### Modal: ModalDialog Custom Height -The `preferredHeightOnMobile` and `preferredHeightFromTabletUp` props were removed and -replaced with one prop `height` which accepts either a single value or -an object with breakpoint keys and values. +The `preferredHeightOnMobile` and `preferredHeightFromTabletUp` props were removed and replaced with a single `height` +prop which accepts either a single value or object with breakpoint keys and values. -Also, the prop `maxHeightFromTabletUp` was removed and replaced with the `maxHeight` prop, -which also accepts either a single value or an object with breakpoint keys and values. +Also, the prop `maxHeightFromTabletUp` was removed and replaced with the `maxHeight` prop, which also accepts either a +single value or an object with breakpoint keys and values. #### Migration Guide -Use codemod to automatically update your codebase. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/modal-custom-height ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. + +
+ 🔧 Manual Migration Steps -Or manually update the `preferredHeightOnMobile` and `preferredHeightFromTabletUp` props to the new `height` prop. +Manually update the `preferredHeightOnMobile` and `preferredHeightFromTabletUp` props to the new `height` prop: - `` → `` - `` → `` - `` → `` -Update the `maxHeightFromTabletUp` prop to the new `maxHeight` prop. +Update the `maxHeightFromTabletUp` prop to the new `maxHeight` prop: - `` → `` +
### Modal: ModalDialog Uniform Appearance -The uniform `ModalDialog` appearance replaced the current behavior. Current mobile appearance -remains accessible via the `isDockedOnMobile` property. +The uniform ModalDialog appearance replaced the current behavior. Current mobile appearance remains accessible via the +`isDockedOnMobile` property. #### Migration Guide -Use codemod to automatically update your codebase. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/modal-isdockeonmobile-prop ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. -Or manually add `isDockedOnMobile` prop to the `ModalDialog` component. +
+ 🔧 Manual Migration Steps + +Manually add the `isDockedOnMobile` prop to the ModalDialog component. + +
### Tabs: TabItem and TabPane Props -TabItem `forTab` prop is renamed to `forTabPane`. -TabPane `tabId` prop is renamed to `id`. +TabItem `forTab` prop was renamed to `forTabPane`. +TabPane `tabId` prop was renamed to `id`. #### Migration Guide -Use codemod to automatically update your codebase. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/tabs-tabitem-tabpane-props ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. + +
+ 🔧 Manual Migration Steps -Or manually replace the props in your project. +Manually replace the props in your project. - `` → `` - `` → `` +
-### TextField: `label` prop +### TextField: `label` Prop -The `label` prop is now required. +The `label` prop is now required by the TextField component. #### Migration Guide -Please ensure that `label` is added to all `TextField` components. -If you need to hide your `label`, you can use the `isLabelHidden` prop. +Please ensure that `label` is added to all instances of the TextField component. +If you need to hide the `label`, you can use the `isLabelHidden` prop. ### Tooltip: `off` Placement @@ -382,16 +458,19 @@ The `off` placement was removed. #### Migration Guide -Please use the new refactored `Tooltip` component. +Please use the new refactored Tooltip component. -### Tooltip: Refactored +### Tooltip: New Structure -The `Tooltip` component was refactored and new structure and API were introduced. +The Tooltip component structure changed and Tooltip (formerly the optional TooltipWrapper) is now a mandatory +wrapping component. Similarly, Tooltip (the tip itself) was renamed to TooltipPopover. #### Migration Guide -See [`Tooltip` documentation][tooltip-readme] for more details and examples. -Tooltip now uses Floating UI library and has a different API. +👉 See [Tooltip documentation][tooltip-readme] for more details and examples. + +Tooltip now has a different API and uses the [Floating UI][floating-ui] library. That's because we found out that most +users want the advanced positioning options anyway. Instead of: @@ -414,26 +493,56 @@ Use: ``` +### Tooltip: Placement Control + +The Tooltip component now supports only [flow-relative cross-axis placements](#placement-in-dropdown-and-tooltip). + +#### Migration Guide + +🪄 Use codemod described in [Placement in Dropdown and Tooltip](#placement-in-dropdown-and-tooltip) to automatically +update your codebase. + +
+ 🔧 Manual Migration Steps + +Manually update cross-axis names in the placement prop: + +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +
+ ### TooltipModern -The `TooltipModern` component was renamed to `Tooltip`. +The TooltipModern component was renamed to Tooltip. #### Migration Guide -Use codemod to automatically update your codebase. +🪄 Use codemod to automatically update your codebase: ```sh npx @lmc-eu/spirit-codemods -p -t v2/web-react/tooltipmodern-component-name ``` -See [Codemods documentation][readme-codemods] for more details. +👉 See [Codemods documentation][readme-codemods] for more details. + +
+ 🔧 Manual Migration Steps + +Manually rename TooltipModern to Tooltip. -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 @@ -441,3 +550,4 @@ Please refer back to these instructions or reach out to our team if you encounte [dropdown-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/src/components/Dropdown/README.md [readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#deprecations [tooltip-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/src/components/Tooltip/README.md +[floating-ui]: https://floating-ui.com diff --git a/docs/migrations/web-twig/MIGRATION-v3.md b/docs/migrations/web-twig/MIGRATION-v3.md index d49985984f..3dd632949e 100644 --- a/docs/migrations/web-twig/MIGRATION-v3.md +++ b/docs/migrations/web-twig/MIGRATION-v3.md @@ -1,21 +1,25 @@ -# Migration Guide WIP +# Migration Guide -Introducing version 3 of the _spirit-web-twig_ package +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 +> available 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) + - [Required `id` Prop in Form Components](#required-id-prop-in-form-components) + - [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: New Structure](#dropdown-new-structure) - [Dropdown: `id` Prop](#dropdown-id-prop) - - [Dropdown: Components Naming](#dropdown-components-naming) + - [Dropdown: Placement Control](#dropdown-placement-control) - [Grid: Breakpoint Props](#grid-breakpoint-props) - [Grid: GridSpan Component](#grid-gridspan-component) - [Header: Abstracts Class and Style](#header-abstracts-class-and-style) @@ -24,7 +28,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) @@ -35,102 +39,105 @@ Introducing version 3 of the _spirit-web-twig_ package The PHP 7.4 is no longer supported. The minimum required PHP version is 8.1. -### Form Components Required `id` Prop +### Required `id` Prop in Form Components -The `id` prop is required for all form components. +The `id` prop is now consistently required by all form components. Affected components: -- `Checkbox` -- `HelperText` -- `Radio` -- `Select` -- `ValidationText` +- Checkbox +- HelperText +- Radio +- Select +- ValidationText #### Migration Guide -Add `id` prop to the form components. +Add the `id` prop to the listed form components. -### Placements in Tooltip and Dropdown +### Placement in Dropdown and Tooltip -The `Tooltip` and `Dropdown` components no longer support non-flow-relative placements. +The Dropdown and Tooltip components now support only flow-relative cross-axis placements. -#### Migration Guide +New [placement naming][dictionary-placement]: -Instead of using `top-left` or `left-bottom` and etc, use `top-start` or `left-end` and so on. -See [Placement dictionary][dictionary-placement] for more details. +1. The main placement axis (top, right, bottom, left) remains the same. +2. The cross axis (formerly also top, right, bottom, left) is now relative to the main axis: start, end. -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` -- `` → `` +#### Migration Guide + +See [Dropdown: Placement Control](#dropdown-placement-control) and [Tooltip: Placement Control](#tooltip-placement-control) +for more details. ## Component Changes ### Alert: `danger` Icon The `danger` icon for `danger` color in the Alert component is now required. -Please, add the `danger` icon to your project's assets. #### Migration Guide -Either install newer version of the `spirit-icons` package or add `danger` named icon to your project's icons. +Either install newer version of the _spirit-icons_ package, or add an icon named `danger` to your project's icons. ### Alert: `role="alert"` -The `role="alert"` has been removed from the default setting of the component. +The `role="alert"` was removed from the default setting of the component. -The alert role is used to communicate an important and usually time-sensitive message to the user. When this role is added to an element, -the browser will send out an accessible alert event to assistive technology products which can then notify the user. -The alert role should only be used for information that requires the user's immediate attention, which is typically -content that is dynamically displayed (such as form validation message etc.), not for content that appears on page load. -It should not be used on HTML that the user hasn't interacted with. +As explained in the [ARIA: alert role][alert-role-documentation] documentation: -For more information see [ARIA: alert role][alert-role-documentation]. +> The alert role is used to communicate an important and usually time-sensitive message to the user. When this role is +> added to an element, the browser will send out an accessible alert event to assistive technology products which can +> then notify the user. The alert role should only be used for information that requires the user's immediate attention, +> which is typically content that is dynamically displayed (such as form validation message etc.), not for content that +> appears on page load. It should not be used on HTML that the user hasn't interacted with. #### Migration Guide -In case you need to use the component as an information that requires the user's immediate attention, -you can use `role="alert"` as an [additional attribute][readme-additional-attributes]. +In case you need to use the component as an information that requires the user's immediate attention, you can use +`role="alert"` as an [additional attribute][readme-additional-attributes]. ### Breadcrumbs: `goBackTitle` Prop -The `goBackTitle` prop is required for the `Breadcrumbs` component. +The `goBackTitle` prop is now required by the Breadcrumbs component. #### Migration Guide -Add `goBackTitle` prop to the `Breadcrumbs` component. +Add the `goBackTitle` prop to the Breadcrumbs component. + +### Dropdown: New Structure + +The Dropdown component structure changed and Dropdown (formerly the optional DropdownWrapper) is now a mandatory +wrapping component. Similarly, Dropdown (the popover itself) was renamed to DropdownPopover. + +#### Migration Guide + +1. Rename the DropdownWrapper component to Dropdown. +2. Rename the Dropdown component to DropdownPopover. ### Dropdown: `id` Prop -The `id` prop is mandatory for the `Dropdown` component. +The `id` prop is now required by the Dropdown component. #### Migration Guide -Add `id` prop to the `Dropdown` component. +Add the `id` prop to the Dropdown component. -### Dropdown: Components Naming +### Dropdown: Placement Control -In order to have the root component called `Dropdown`, we renamed -the `DropdownWrapper` component to `Dropdown` and the original -`Dropdown` component to `DropdownPopover`. +The Dropdown component now supports only [flow-relative cross-axis placements](#placement-in-dropdown-and-tooltip). #### Migration Guide -1. Rename `DropdownWrapper` component to `Dropdown`. -2. Rename `Dropdown` component to `DropdownPopover`. +Update cross-axis names in the placement prop: + +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` ### Grid: Breakpoint Props @@ -147,34 +154,50 @@ Replace `tablet` and `desktop` props with the `cols` object prop. ### Grid: GridSpan Component -The `GridSpan` component was removed. Use `GridItem` instead. +The GridSpan component was removed. Instead, you can use the more powerful GridItem component that allows you to define +the start and end columns for each breakpoint. #### Migration Guide The hardest part in the migration is to get the `columnStart` value. The equation is `1 + (columns - over) / 2`, -where `columns` is the number of columns in the grid and `over` is the value from the `GridSpan` component. +where `columns` is the number of columns in the grid and `over` is the value from the GridSpan component. The default number of columns is 12, so the equation is `1 + (12 - over) / 2` most of the time. 1. Replace `GridSpan` with `GridItem`. -2. Calculate and set the `columnStart` value `1 + (columns - over) / 2`, in our 12-column grid, the equation is `1 + (12 - over) / 2`, where `over` is the value from the `GridSpan` component. -3. Set the `columnEnd` value to `span over` or you can use `columnStart + over`. -4. If you use responsive props, calculate the values for each breakpoint and pass them to the `GridItem` component `columnStart` and `columnEnd` props as an object. +2. Calculate and set the `columnStart` value `1 + (columns - over) / 2`, in our 12-column grid, the equation is `1 + (12 - over) / 2`, where `over` is the value from the GridSpan component. +3. Set the `columnEnd` value to `span over` or use `columnStart + over`. +4. If you use responsive props, calculate the values for each breakpoint and pass them to the GridItem component `columnStart` and `columnEnd` props as an object. 5. Remove the `over` prop. -Examples: - -- `…` → `…` - - `columnStart` = 1 + (12 - 4) / 2 = 5 -- `…` → `…` - - `columnStart` = 1 + (12 - 6) / 2 = 4 -- `…` → `…` +##### Examples + +- Centered grid item over 4 columns: + ```diff + -… + +… + ``` + `columnStart` = 1 + (12 - 4) / 2 = 5 +- Centered grid item over 6 columns: + ```diff + -… + +… + ``` + `columnStart` = 1 + (12 - 6) / 2 = 4 +- Responsive grid item centered over 8 columns on mobile, 6 columns on tablet, and 4 columns on desktop: + ```diff + -… + +… + ``` - `columnStart` = 1 + (12 - 8) / 2 = 3 - `columnStart` = 1 + (12 - 6) / 2 = 4 - `columnStart` = 1 + (12 - 4) / 2 = 5 ### Header: Abstracts Class and Style -The `style` and `class` props were removed from these `Header` abstracts: +The `style` and `class` props were removed from these Header abstracts: - `Header/_abstracts/Button` - `Header/_abstracts/Element` @@ -188,82 +211,77 @@ Replace `style` with `UNSAFE_style` and `class` with `UNSAFE_className`. ### Header: HeaderDesktopActions `isAtEnd` prop -The `HeaderDesktopActions` component slots were simplified and the second slot alignment is now -available by using the `isAtEnd` prop. +The HeaderDesktopActions component slots were simplified and the second slot alignment is now available by using the +`isAtEnd` prop. -The `HeaderDesktopActions` prop `color` was removed. +The HeaderDesktopActions `color` prop was removed. #### Migration Guide -Use the `HeaderDesktopActions` with `isAtEnd` prop instead of the `color="secondary"` prop. -Remove the `color` prop from the `HeaderDesktopActions` component. +Use the HeaderDesktopActions component with the `isAtEnd` prop instead of the `color="secondary"` prop. +Remove the `color` prop from the HeaderDesktopActions component. - `` → `` - `` → `` ### Modal: ModalDialog `isScrollable` Prop -The `isScrollable` prop is now set to `false` by default and the ModalDialog is non-scrollable by default. +The default value of the `isScrollable` prop is now set to `false` and the ModalDialog is non-scrollable by default. It is possible to re-enable the inside scrolling by adding the `isScrollable` prop. #### Migration Guide -Add `isScrollable` prop to the `ModalDialog` component. +Add `isScrollable` prop to the ModalDialog component. -If you use `ScrollView` for scrolling the content of your modal, you must also make the -`ModalDialog` scrollable by setting the `isScrollable` prop. +If you use ScrollView for scrolling the content of your modal, you must also make the ModalDialog scrollable by setting +the `isScrollable` prop. ### Modal: ModalDialog Custom Height -The `preferredHeightOnMobile` and `preferredHeightFromTabletUp` props were removed and -replaced with one prop `height` which accepts either a single value or -object with breakpoint keys and values. +The `preferredHeightOnMobile` and `preferredHeightFromTabletUp` props were removed and replaced with a single `height` +prop which accepts either a single value or object with breakpoint keys and values. -Also, the prop `maxHeightFromTabletUp` was removed and replaced with the `maxHeight` prop, -which also accepts either a single value or object with breakpoint keys and values. +Also, the prop `maxHeightFromTabletUp` was removed and replaced with the `maxHeight` prop, which also accepts either a +single value or an object with breakpoint keys and values. #### Migration Guide -Update the `preferredHeightOnMobile` and `preferredHeightFromTabletUp` props to the new `height` prop. +Update the `preferredHeightOnMobile` and `preferredHeightFromTabletUp` props to the new `height` prop: - `` → `` - `` → `` - `` → `` -Update the `maxHeightFromTabletUp` prop to the new `maxHeight` prop. +Update the `maxHeightFromTabletUp` prop to the new `maxHeight` prop: - `` → `` ### Modal: ModalDialog Uniform Appearance -The uniform `ModalDialog` appearance replaced the current behavior. Current mobile appearance -remains accessible via the `isDockedOnMobile` property. +The uniform ModalDialog appearance replaced the current behavior. Current mobile appearance remains accessible via the +`isDockedOnMobile` property. #### Migration Guide -Add `isDockedOnMobile` prop to the `ModalDialog` component. +Add the `isDockedOnMobile` prop to the ModalDialog component. ### Tabs: TabLink `target` Prop -The `target` prop was renamed to `targetPaneId` in the `TabLink` component. +The `target` prop was renamed to `targetPaneId` in the TabLink component. -The reason for this change is to avoid confusion with the -[`target` attribute][mdn-anchor-target] in the anchor tag. +The reason for this change is to avoid confusion with the [`target` attribute][mdn-anchor-target] of the anchor tag. #### Migration Guide -Replace `target` with `targetPaneId` in the `TabLink` component. +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 -itself) was renamed to `TooltipPopover`. +The Tooltip component structure changed and Tooltip (formerly the optional TooltipWrapper) is now a mandatory +wrapping component. Similarly, Tooltip (the tip itself) was renamed to TooltipPopover. #### Migration Guide -Use `TooltipPopover` in you project. - Instead of: ```twig @@ -295,16 +313,16 @@ Use: ``` -See [`Tooltip` documentation][tooltip-readme] for more details and examples. +👉 See [Tooltip documentation][tooltip-readme] for more details and examples. ### Tooltip: Hidden By Default -The `TooltipPopover` component is now hidden by default. -Use `isOpen` prop to show the Tooltip on initial render. +The TooltipPopover component is now hidden by default. Use the `isOpen` prop to show the Tooltip on initial render. #### Migration Guide -Use `isOpen` prop in `TooltipPopover` instead of `UNSAFE_className="is-hidden"` for setting whether it should be opened or closed on initial render. +Use `isOpen` prop in TooltipPopover instead of `UNSAFE_className="is-hidden"` for setting whether it should be opened or +closed on initial render. Instead of: @@ -342,12 +360,33 @@ Use: ``` -See [`Tooltip` documentation][tooltip-readme] for more details and examples. +👉 See [Tooltip documentation][tooltip-readme] for more details and examples. + +### Tooltip: Placement Control + +The Tooltip component now supports only [flow-relative cross-axis placements](#placement-in-dropdown-and-tooltip) +controlled via the `data-spirit-placement` attribute. + +#### Migration Guide + +Update cross-axis names in the placement prop: + +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` +- `` → `` ### Tooltip: TooltipPopover `enableControlledPlacement` Prop -We have decided to stop support for non-FloatingUI and CSS-only tooltips. -As a result, the `enableControlledPlacement` prop is no longer mandatory for the `TooltipPopover` component, as all tooltips now use FloatingUI. +Tooltip now has a different API and uses the [Floating UI][floating-ui] library. That's because we found out that +most users want the advanced positioning options anyway. + +As a result, the `enableControlledPlacement` prop is no longer mandatory for the TooltipPopover component, as all +Tooltips now are controlled by Floating UI. #### Migration Guide @@ -370,7 +409,6 @@ Instead of: Hello there! - ``` Use: @@ -393,19 +431,20 @@ Use: ``` -See [`Tooltip` documentation][tooltip-readme] for more details and examples. +👉 See [Tooltip documentation][tooltip-readme] for more details and examples. ### Tooltip: TooltipPopover Default Values -Tooltip props `enableFlipping`, `enableFlippingCrossAxis`, `enableShifting`, and `enableSizing` are now turned on by default. -You can turn them off by setting them to `false`. +Tooltip props `enableFlipping`, `enableFlippingCrossAxis`, `enableShifting`, and `enableSizing` are now turned on by +default. You can turn them off by setting them to `false`. -See [`Tooltip` documentation][tooltip-readme] for more details and examples. +👉 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 @@ -413,3 +452,4 @@ Please refer back to this guide or reach out to our team if you encounter any is [readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes [readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#deprecations [tooltip-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/Tooltip/README.md +[floating-ui]: https://floating-ui.com diff --git a/docs/migrations/web/MIGRATION-v2.md b/docs/migrations/web/MIGRATION-v2.md index 7bea6c80b4..60c055fb84 100644 --- a/docs/migrations/web/MIGRATION-v2.md +++ b/docs/migrations/web/MIGRATION-v2.md @@ -1,26 +1,32 @@ -# Migration Guide WIP +# Migration Guide -Introducing version 2 of the _spirit-web_ package +Introducing version 2 of the _spirit-web_ package. > Please follow these steps to safely upgrade to Spirit Design System v2 components. ## Overview - [General Changes](#general-changes) - - [Dropped Support for Node.js 16](#dropped-support-for-node-js-16) + - [Dropped Support for Node.js 16](#dropped-support-for-nodejs-16) - [CSS Variables Component Prefix](#css-variables-component-prefix) - - [Placement in Tooltip and Dropdown](#placement-in-tooltip-and-dropdown) + - [Placement in Dropdown and Tooltip](#placement-in-dropdown-and-tooltip) +- [Feature Flags](#feature-flags) + - [Alert: Border](#alert-border) + - [Dropdown: Shadow](#dropdown-shadow) + - [Modal: Uniform Variant](#modal-uniform-variant) + - [Tooltip: Controlled Placement](#tooltip-controlled-placement) +- [JavaScript Plugins](#javascript-plugins) + - [Tooltip: Floating UI only](#tooltip-floating-ui-only) - [Component Changes](#component-changes) - - [Alert: Bordered Feature Flag](#alert-bordered-feature-flag) - - [Dropdown: Classes](#dropdown-classes) + - [Dropdown: New Structure](#dropdown-new-structure) + - [Dropdown: Placement Control](#dropdown-placement-control) - [Dropdown: Combined Placements](#dropdown-combined-placements) - - [Dropdown: Shadow Feature Flag](#dropdown-shadow-feature-flag) + - [Grid: GridSpan Component](#grid-gridspan-component) - [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) + - [Tooltip: Placement Control](#tooltip-placement-control) ## General Changes @@ -44,64 +50,119 @@ 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. +The `Tooltip` and `Dropdown` components now support only flow-relative cross-axis placements. -Also, placement classes for Tooltip and Dropdown were removed. +1. New [placement naming][dictionary-placement]: + 1. The main placement axis (top, right, bottom, left) remains the same. + 2. The cross axis (formerly also top, right, bottom, left) is now relative to the main axis: start, end. +2. Component-specific placement CSS classes were removed. All placements in the _spirit-web_ package are now controlled + by the `data-spirit-placement` attribute. #### Migration Guide -Instead of using `Tooltip--top`/`Dropdown--top` or `Tooltip--topLeft`/`Dropdown--topLeft`, -use data attribute like `data-spirit-placement="top"` or `data-spirit-placement="top-start"`. -See [Placement dictionary][dictionary-placement] for more details. - -- `.Tooltip--topLeft` → `data-spirit-placement="top-start"` -- `.Tooltip--top` → `data-spirit-placement="top"` -- `.Tooltip--topRight` → `data-spirit-placement="top-end"` -- `.Tooltip--rightTop` → `data-spirit-placement="right-start"` -- `.Tooltip--right` → `data-spirit-placement="right"` -- `.Tooltip--rightBottom` → `data-spirit-placement="right-end"` -- `.Tooltip--bottomRight` → `data-spirit-placement="bottom-end"` -- `.Tooltip--bottom` → `data-spirit-placement="bottom"` -- `.Tooltip--bottomLeft` → `data-spirit-placement="bottom-start"` -- `.Tooltip--leftBottom` → `data-spirit-placement="left-end"` -- `.Tooltip--left` → `data-spirit-placement="left"` -- `.Tooltip--leftTop` → `data-spirit-placement="left-start"` -- `.Dropdown--topLeft` → `data-spirit-placement="top-start"` -- `.Dropdown--top` → `data-spirit-placement="top"` -- `.Dropdown--topRight` → `data-spirit-placement="top-end"` -- `.Dropdown--rightTop` → `data-spirit-placement="right-start"` -- `.Dropdown--right` → `data-spirit-placement="right"` -- `.Dropdown--rightBottom` → `data-spirit-placement="right-end"` -- `.Dropdown--bottomRight` → `data-spirit-placement="bottom-end"` -- `.Dropdown--bottom` → `data-spirit-placement="bottom"` -- `.Dropdown--bottomLeft` → `data-spirit-placement="bottom-start"` -- `.Dropdown--leftBottom` → `data-spirit-placement="left-end"` -- `.Dropdown--left` → `data-spirit-placement="left"` -- `.Dropdown--leftTop` → `data-spirit-placement="left-start"` +See [Dropdown: Placement Control](#dropdown-placement-control) and [Tooltip: Placement Control](#tooltip-placement-control) +for more details about usage of the _spirit-web_ package implementation. -## Component Changes +## Feature Flags -### Alert: Bordered Feature Flag +### Alert: Border The feature flag enabling the bordered variant of alert was removed and the bordered variant -is the default. +is now default. #### Migration Guide 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 + +The feature flag enabling the dropdown shadow was removed and the enhanced +shadow is now 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 + +The feature flag enabling the uniform variant of modal was removed and the +uniform variant is now 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 + +The feature flag enabling the data-selector-controlled placement (`data-spirit-placement-controlled`) for the tooltip +was removed. The controlled placement is now 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 + +> ℹ️ Do you use the _spirit-web-react_ package? Congratulations, you are done here! 🎉 +> Please refer to the migration guide for the changes in the React components. + +### Tooltip: Floating UI only + +Non-Floating-UI and CSS-only Tooltips are no longer supported. That's because we found out that most users want the +advanced positioning options anyway. The Tooltip component is now dependent on the [Floating UI][floating-ui] library +and has a new structure. See the updated [Tooltip documentation][readme-tooltip] for more details on how to use Tooltip +now. + +#### Migration Guide + +Delete the [controlled placement feature flag](#tooltip-controlled-placement) and follow the +[new Tooltip structure](#tooltip-new-structure). + +## Component Changes + +> ℹ️ Do you use the _spirit-web-react_ or _spirit-web-twig_ package? Congratulations, you are done here! 🎉 +> Please refer to the respective migration guide for the changes in the React or Twig components. -In order to have the root element called `Dropdown` we renamed the `DropdownWrapper` -component to `Dropdown` and the original `Dropdown` component to `DropdownPopover`. +### Dropdown: New Structure + +The Dropdown component structure changed and Dropdown (formerly the optional DropdownWrapper) is now a mandatory +wrapping component. Similarly, Dropdown (the popover itself) was renamed to DropdownPopover. + +#### Migration Guide + +1. Rename `.Dropdown` to `.DropdownPopover`. +2. Fix the wrapper: + 1. either add a new `.Dropdown` component wrapping the `.DropdownPopover`, or + 2. rename your existing `.DropdownWrapper` to `.Dropdown`. + +### Dropdown: Placement Control + +The Dropdown component now supports only [flow-relative cross-axis placements](#placement-in-dropdown-and-tooltip) +controlled via the `data-spirit-placement` attribute. #### Migration Guide -1. Rename `Dropdown` to `DropdownPopover`. -2. Rename `DropdownWrapper` to `Dropdown`. +Instead of using `.Dropdown--top` or `.Dropdown--topLeft`, use a data attribute like `data-spirit-placement="top"` or +`data-spirit-placement="top-start"`. + +- `.Dropdown--topLeft` → `data-spirit-placement="top-start"` +- `.Dropdown--top` → `data-spirit-placement="top"` +- `.Dropdown--topRight` → `data-spirit-placement="top-end"` +- `.Dropdown--rightTop` → `data-spirit-placement="right-start"` +- `.Dropdown--right` → `data-spirit-placement="right"` +- `.Dropdown--rightBottom` → `data-spirit-placement="right-end"` +- `.Dropdown--bottomRight` → `data-spirit-placement="bottom-end"` +- `.Dropdown--bottom` → `data-spirit-placement="bottom"` +- `.Dropdown--bottomLeft` → `data-spirit-placement="bottom-start"` +- `.Dropdown--leftBottom` → `data-spirit-placement="left-end"` +- `.Dropdown--left` → `data-spirit-placement="left"` +- `.Dropdown--leftTop` → `data-spirit-placement="left-start"` ### Dropdown: Combined Placements @@ -109,7 +170,7 @@ Combined placement classes for Dropdown were removed. #### Migration Guide -Instead of using `.Dropdown--bottom.Dropdown--left`, use combination `bottom-start` in placement data attribute. +Instead of using `.Dropdown--bottom.Dropdown--left`, use a combined value of `bottom-start` in the placement data attribute. - `.Dropdown--top.Dropdown--left` → `data-spirit-placement="top-start"` - `.Dropdown--top.Dropdown--right` → `data-spirit-placement="top-end"` @@ -120,26 +181,69 @@ 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 +### Grid: GridSpan Component -The feature flag enabling the dropdown shadow was removed and the enhanced -shadow is the default. +The GridSpan component was removed. Instead, you can use the more powerful GridItem component that allows you to define +the start and end columns for each breakpoint. #### 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. +1. Replace `.Grid__span` with `.GridItem`. +2. Calculate and set the CSS variable `--grid-item-column-start` value `1 + (columns - over) / 2`, in our 12-column grid, the equation is `1 + (12 - over) / 2`, where `over` is the number from the `Grid__span--over-*` modifier. +3. Set the CSS variable `--grid-item-column-end` value to `span over` or you can use calculated `--grid-item-column-start + over`. +4. If you use responsive props, repeat the process for each breakpoint and set the values to the `--grid-item-column-start-breakpoint` and `--grid-item-column-end-breakpoint` variables. +5. Remove any `.Grid__span--*` modifier classes. + +##### Examples + +- Centered grid item over 4 columns: + ```diff + -
…
+ +
…
+ ``` + `column-start` = 1 + (12 - 4) / 2 = 5 +- Centered grid item over 6 columns: + ```diff + -
…
+ +
…
+ ``` + `column-start` = 1 + (12 - 6) / 2 = 4 +- Responsive grid item centered over 8 columns on mobile, 6 columns on tablet, and 4 columns on desktop: + ```diff + -
…
+ +
…
+ ``` + - `column-start` = 1 + (12 - 8) / 2 = 3 + - `column-start` = 1 + (12 - 6) / 2 = 4 + - `column-start` = 1 + (12 - 4) / 2 = 5 ### Header: HeaderDesktopActions Alignment -The `HeaderDesktopActions` component slots were simplified and the second slot alignment is now -available by using the `HeaderDesktopActions--end` modifier. +The HeaderDesktopActions component slots were simplified and the second slot alignment is now +available by using the `.HeaderDesktopActions--end` modifier. -The `HeaderDesktopActions--primary` and `HeaderDesktopActions--secondary` modifier classes were removed. +The `.HeaderDesktopActions--primary` and `.HeaderDesktopActions--secondary` modifier classes were removed. #### Migration Guide -Use the `.HeaderDesktopActions--end` modifier class instead of the `HeaderDesktopActions--secondary` modifier class. +Use the `.HeaderDesktopActions--end` modifier class instead of the `.HeaderDesktopActions--secondary` modifier class. - `.HeaderDesktopActions.HeaderDesktopActions--primary` → `.HeaderDesktopActions` - `.HeaderDesktopActions.HeaderDesktopActions--secondary` → `.HeaderDesktopActions.HeaderDesktopActions--end` @@ -152,15 +256,15 @@ The `.ModalDialog--nonScrollable` modifier was removed and the ModalDialog is ma In the new version, use the `.ModalDialog--scrollable` modifier class to make the ModalDialog scrollable. -If you use `ScrollView` for scrolling the content of your modal, you must also add the `.ModalDialog--scrollable` class +If you use ScrollView for scrolling the content of your Modal, you must also add the `.ModalDialog--scrollable` class to the `.ModalDialog` element. -- `.ModalDialog` → `.ModalDialog .ModalDialog--scrollable` +- `.ModalDialog` → `.ModalDialog.ModalDialog--scrollable` ### Modal: Custom Height -The `--modal-preferred-height-mobile`, `--modal-preferred-height-tablet`, -`--modal-max-height-tablet` custom properties were renamed. +The `--modal-preferred-height-mobile`, `--modal-preferred-height-tablet`, `--modal-max-height-tablet` custom properties +were renamed. #### Migration Guide @@ -170,48 +274,45 @@ 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 +### Tooltip: New Structure -The feature flag enabling the uniform variant of modal was removed and the -uniform variant is the default. +The Tooltip component structure changed and Tooltip (formerly the optional TooltipWrapper) is now a mandatory +wrapping component. Similarly, Tooltip (the tip itself) was renamed to TooltipPopover. #### 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 +1. Rename `.Tooltip` to `.TooltipPopover`. +2. Fix the wrapper: + 1. either add a new `.Tooltip` component wrapping the `.TooltipPopover`, or + 2. rename your existing `.TooltipWrapper` to `.Tooltip`. -The `GridSpan` component was removed and the `GridItem` component should be used instead. +Also, Tooltip now has a different API and uses the [Floating UI][floating-ui] library. That's because we found out that +most users want the advanced positioning options anyway. -#### Migration Guide - -1. Replace `Grid__span` with `GridItem`. -2. Calculate and set the CSS variable `--grid-item-column-start` value `1 + (columns - over) / 2`, in our 12-column grid, the equation is `1 + (12 - over) / 2`, where `over` is the number from the `Grid__span--over-*` modifier. -3. Set the CSS variable `--grid-item-column-end` value to `span over` or you can use calculated `--grid-item-column-start + over`. -4. If you use responsive props, repeat the process for each breakpoint and set the values to the `--grid-item-column-start-breakpoint` and `--grid-item-column-end-breakpoint` variables. -5. Remove `Grid__span--*` modifier classes. - -- `
…
` → `
…
` - - `column-start` = 1 + (12 - 4) / 2 = 5 -- `
…
` → `
…
` - - `column-start` = 1 + (12 - 6) / 2 = 4 -- `
…
` → `
…
` - - `column-start` = 1 + (12 - 8) / 2 = 3 - - `column-start` = 1 + (12 - 6) / 2 = 4 - - `column-start` = 1 + (12 - 4) / 2 = 5 +See [Tooltip documentation][readme-tooltip] for more details and examples. -### Tooltip: FloatingUI only +### Tooltip: Placement Control -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. +The Tooltip component now supports only [flow-relative cross-axis placements](#placement-in-dropdown-and-tooltip) +controlled via the `data-spirit-placement` attribute. #### 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. -Please follow new Tooltip structure. +Instead of using `.Tooltip--top` or `.Tooltip--topLeft`, use a data attribute like `data-spirit-placement="top"` or +`data-spirit-placement="top-start"`. + +- `.Tooltip--topLeft` → `data-spirit-placement="top-start"` +- `.Tooltip--top` → `data-spirit-placement="top"` +- `.Tooltip--topRight` → `data-spirit-placement="top-end"` +- `.Tooltip--rightTop` → `data-spirit-placement="right-start"` +- `.Tooltip--right` → `data-spirit-placement="right"` +- `.Tooltip--rightBottom` → `data-spirit-placement="right-end"` +- `.Tooltip--bottomRight` → `data-spirit-placement="bottom-end"` +- `.Tooltip--bottom` → `data-spirit-placement="bottom"` +- `.Tooltip--bottomLeft` → `data-spirit-placement="bottom-start"` +- `.Tooltip--leftBottom` → `data-spirit-placement="left-end"` +- `.Tooltip--left` → `data-spirit-placement="left"` +- `.Tooltip--leftTop` → `data-spirit-placement="left-start"` --- @@ -221,3 +322,4 @@ Please refer back to these instructions or reach out to our team if you encounte [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 [readme-tooltip]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/src/scss/components/Tooltip/README.md +[floating-ui]: https://floating-ui.com