@splunk/react-ui 4.38.0 → 4.40.0

package/MIGRATION.mdx

@@ -5,6 +5,78 @@ import Table from '@splunk/react-ui/Table';
 
 This document lists migration guidance for new features and breaking changes.
 
+## 4.40.0
+
+### Deprecated `Select`'s `appearance="primary"` value
+
+#### Change
+
+`Select`'s `appearance="primary"` value has been deprecated and will be removed in the next major version.
+
+#### Context
+
+The `primary` appearance is no longer supported as primary actions are generally intended for tasks like submitting a form or page, whereas `Select` should be used to make a choice that then gets submitted with a primary `Button`. 
+Including both a primary `Select` and `Button` conflicts with the visual importance and hierarchy of the page.
+
+#### Migration steps
+
+* If `Select` was being used as a primary action but there are some variants for how that primary action works (e.g. Save vs. Save As), use `SplitButton`.
+* Otherwise use `Select` with the `default` appearance paired with a primary `Button` to submit.
+
+## 4.39.0
+
+### Deprecated `TabBar` and `TabLayout`'s `appearance` prop
+
+#### Change
+
+`TabBar` and `TabLayout`'s `appearance` prop is deprecated and will be removed in the next major version.
+
+#### Context
+
+The `appearance` prop exists to support the `"context"` appearance, which renders tabs without the divider separating the tab and its contents. It also does not underline the active tab.
+
+Due to these factors, the `"context"` appearance has poor accessibility on two fronts:
+* it makes it difficult to distinguish the tabs from the content
+* it has poor contrast between the selected and unselected tabs
+
+The existance of this appearance has also encouraged uses of these components where tabs are not appropriate.
+
+Additionally, this appearance has only been supported in Prisma themes, leading to visual inconsistency with Enterprise themes.
+
+To eliminate these issues, we have deprecated the `appearance` prop.
+
+#### Migration steps
+
+Remove usages of the `appearance` prop:
+
+1) If you were using `appearance="navigation"`, that is the default appearance and removing the prop will have no effect.
+2) If you were using `appearance="context"`, the tabs will render with the default appearance.
+
+### Deprecated `Button`'s `selected` prop
+
+#### Change
+
+`Button`'s `selected` prop is deprecated and will be removed in the next major version.
+
+#### Context
+
+By existing on the `Button` component, the `selected` attribute had to account for prop combinations that were invalid.
+For example, `appearance="primary"` is not a valid combination with `selected`, but both those props exist in tandem on `Button`.
+
+Additionally, the `selected` prop in isolation is unable to provide sufficient accessibility.
+For example, using it inside a `ButtonGroup` appears correct, but both the `ButtonGroup` and the `Button` require additional aria attributes to be accessible.
+
+Given these issues and the usages of the `selected` prop that we've observed, we believe that one of the options outlined in the migration steps can provide the required functionality without the aforementioned visual and accessibility issues.
+
+If these alternatives do not match your use case, please reach out to us.
+
+#### Migration steps
+
+There are two possible use cases for a selectable `Button`:
+
+1) If the `Button` was used as part of a `ButtonGroup`, replace it with a `RadioBar`.
+2) If the `Button` was used standalone, replace it with a `Switch` with `appearance="toggle"`.
+
 ## 4.35.0
 
 ### Deprecated `Menu`'s `retainFocus` prop
@@ -39,7 +111,7 @@ The original `retainFocus={true}` is no longer supported due to its poor user ex
 
 #### Context
 
-The `"pill"` value for `appearance` was only supported in Enterprise theme, and the `"flat"` and `"toggle"` values were only supported in the Prisma theme.
+The `"pill"` value for `appearance` was only supported in Enterprise themes, and the `"flat"` and `"toggle"` values were only supported in Prisma themes.
 
 As part of our effort to unify behaviors and APIs across themes, we are deprecating these appearances.
 
@@ -118,14 +190,14 @@ For Prisma themes:
 
 #### Context
 
-Previously, `titleWithActions` prop allowed for customized interactive elements to be added directly to the `title` prop. 
-Now, a new `actions` prop is introduced to reserve the `title` prop for text only. The `actions` prop should contain all customized 
-interactive actions that were previously placed in the `title` prop. This ensures that the controls are not read as part of the label, 
+Previously, `titleWithActions` prop allowed for customized interactive elements to be added directly to the `title` prop.
+Now, a new `actions` prop is introduced to reserve the `title` prop for text only. The `actions` prop should contain all customized
+interactive actions that were previously placed in the `title` prop. This ensures that the controls are not read as part of the label,
 while still providing the necessary interactivity.
 
 #### Migration steps
 
-Remove `CollapsiblePanel`'s `titleWithActions` prop. Extract the actions/interactive elements from the `title` prop 
+Remove `CollapsiblePanel`'s `titleWithActions` prop. Extract the actions/interactive elements from the `title` prop
 and move them to the new `actions` prop.
 
 ## 4.30.0
@@ -189,14 +261,14 @@ Example with a sibling text element:
 ### New `SingleOpenPanelGroup` API for `CollapsiblePanel`
 
 #### Change
-A new API, `SingleOpenPanelGroup`, has been added to `CollapsiblePanel`. 
+A new API, `SingleOpenPanelGroup`, has been added to `CollapsiblePanel`.
 
 #### Context
 `Accordion` and `CollapsiblePanel` have similar style and behavior. Their only behavioral difference was that `Accordion` would only allow one panel to be open at a time, whereas `CollapsiblePanel` would allow multiple panels to be open at a time.
 
-Although they looked and behaved similarly, the APIs of `Accordion` and `CollapsiblePanel` were inconsistent. `inset` was supported in `Accordion` but not `CollapsiblePanel`; while actions were supported in `CollapsiblePanel` but not `Accordion`. Lastly, the components had different numbers of event handlers with different signatures. 
+Although they looked and behaved similarly, the APIs of `Accordion` and `CollapsiblePanel` were inconsistent. `inset` was supported in `Accordion` but not `CollapsiblePanel`; while actions were supported in `CollapsiblePanel` but not `Accordion`. Lastly, the components had different numbers of event handlers with different signatures.
 
-These differences could lead to confusion on which component to use. It could also lead to using one component for a certain feature and then adding custom code to duplicate the functionality from the other component. 
+These differences could lead to confusion on which component to use. It could also lead to using one component for a certain feature and then adding custom code to duplicate the functionality from the other component.
 
 Given these behavioral and technical differences, `Accordion` will be deprecated in the next major version and `CollapsiblePanel` will support all the features of `Accordion` through its `SingleOpenPanelGroup` API. You will still be able to use `Accordion` in the next major version, but we recommend following the migration steps below at your earliest convenience.
 
@@ -206,10 +278,10 @@ Replace usage of `Accordion` with the `SingleOpenPanelGroup` component exported
 ### Deprecated `onRequestClose` and `onRequestOpen` callbacks and added new `onChange` callback for `CollapsiblePanel`
 
 #### Change
-`CollapsiblePanel`'s `onRequestClose` and `onRequestOpen` callbacks have been deprecated and will be removed in the next major version. A new callback `onChange` has been added to `CollapsiblePanel`. 
+`CollapsiblePanel`'s `onRequestClose` and `onRequestOpen` callbacks have been deprecated and will be removed in the next major version. A new callback `onChange` has been added to `CollapsiblePanel`.
 
 #### Context
-An `onChange` callback is more consistent with other components in `@splunk/react-ui`. 
+An `onChange` callback is more consistent with other components in `@splunk/react-ui`.
 
 #### Migration steps
 Replace `onRequestClose` and `onRequestOpen` callbacks with the new `onChange` callback when using a controlled `CollapsiblePanel`. See the Controlled example in `CollapsiblePanel`'s documentation.
@@ -219,16 +291,16 @@ Replace `onRequestClose` and `onRequestOpen` callbacks with the new `onChange` c
 ### New `returnFocus` prop for `Modal`
 
 #### Change
-A new prop, `returnFocus`, has been added to `Modal`. `returnFocus` is optional for backwards compatibility but will be required in the next major version. 
+A new prop, `returnFocus`, has been added to `Modal`. `returnFocus` is optional for backwards compatibility but will be required in the next major version.
 
 #### Context
-Failing to return focus back to the invoking element (or another logical place) is a WCAG violation. Currently, 
+Failing to return focus back to the invoking element (or another logical place) is a WCAG violation. Currently,
 developers must remember to manually return focus. The `returnFocus` prop will be required in the next major version
-and ensure focus is returned back to the invoking element. 
+and ensure focus is returned back to the invoking element.
 
 #### Migration steps
-Previously it was required to add code to manually return focus in `onRequestClose` for the `Modal` and `Modal.Header`. 
-This code can now be removed and replaced by passing the invoking element's ref to the new `returnFocus` prop on `Modal`. 
+Previously it was required to add code to manually return focus in `onRequestClose` for the `Modal` and `Modal.Header`.
+This code can now be removed and replaced by passing the invoking element's ref to the new `returnFocus` prop on `Modal`.
 
 For example, this code snippet:
 ```jsx
@@ -267,7 +339,7 @@ can be converted to this code:
 ### Deprecated `JSONTree`'s `expandChildren="withShiftModifier"` value
 
 #### Change
-`JSONTree`'s `expandChildren="withShiftModifier"` value has been deprecated and will be removed in a future major version. A new prop `expandChildrenOnShiftKey` has been added to `JSONTree` to expand all descendant nodes when using `shift + click` or `shift + enter`. 
+`JSONTree`'s `expandChildren="withShiftModifier"` value has been deprecated and will be removed in a future major version. A new prop `expandChildrenOnShiftKey` has been added to `JSONTree` to expand all descendant nodes when using `shift + click` or `shift + enter`.
 
 #### Context
 Separating the `shift + click` capability from `expandChildren` allows users to decide if they want to enable `shift + click` to expand all descendant nodes independently of
@@ -281,13 +353,13 @@ Replace all usage of `JSONTree`'s `expandChildren="withShiftModifier"` value wit
 ### Deprecated `level="s"` and `level="ss"` and added new `variant` prop for `Heading`
 
 #### Change
-`Heading`'s `level="s"` and `level="ss"` have been deprecated and will be removed in a future major version. A new prop `variant` has been added to `Heading` to add styles from `Typography`'s title variants. 
+`Heading`'s `level="s"` and `level="ss"` have been deprecated and will be removed in a future major version. A new prop `variant` has been added to `Heading` to add styles from `Typography`'s title variants.
 
 #### Context
 The values "s" and "ss" aren't as clear as numerical values at describing which `<hX>` HTML tag they correspond to. Instead, use `Heading` `level`(1 - 6) and `variant`(title1 - title6) props to achieve the desired `Heading` style. This separates the concerns of semantics from styling, which allows for better accessibility and design.
 
 #### Migration steps
-It is recommended to update `Heading`'s `level="s"` and `level="ss"` to `level=5` or `level=6` respectively and use the `variant` prop for styling. 
+It is recommended to update `Heading`'s `level="s"` and `level="ss"` to `level=5` or `level=6` respectively and use the `variant` prop for styling.
 To keep the same style as `Heading`'s `level="s"` and `level="ss"` follow the below code:
 
 *Enterprise*
@@ -330,13 +402,13 @@ const StyledSHeading = styled(Heading)`
     color: ${variables.contentColorDefault};
 `;
 
-<StyledSHeading level={4} variant="title4"/> 
+<StyledSHeading level={4} variant="title4"/>
 ```
 
 `level="ss"` styling:
 
 ```jsx
-No styling is needed. 
+No styling is needed.
 <Heading level="ss"> is equivalent to <StyledSHeading level={5} variant="title5"/>
 ```
 
@@ -351,7 +423,7 @@ Additionally, when entering text into a `TextArea` users can clear the contents
 
 #### Migration Step
 
-Remove the `canClear` prop from `TextArea`. If supporting a one-click clear action is critical, there are two possible methods to add this feature: 
+Remove the `canClear` prop from `TextArea`. If supporting a one-click clear action is critical, there are two possible methods to add this feature:
 
 1) Use the `endAdornment` prop:
 
@@ -420,7 +492,7 @@ Themes has new variables in version 4.17.0 that support all of the weight values
 This aligns with the existing API for `variant` in this component.
 
 #### Migration steps
-Convert any usage of a number to the keyword value using the following table based on <Link to="https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight#common_weight_name_mapping" openInNewContext>MDN</Link>: 
+Convert any usage of a number to the keyword value using the following table based on <Link to="https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight#common_weight_name_mapping" openInNewContext>MDN</Link>:
 
 <Table>
     <Table.Head>
@@ -460,7 +532,7 @@ Convert any usage of a number to the keyword value using the following table bas
 </Table>
 
 For example, convert `<Typography as="p" weight={700} />` to `<Typography as="p" weight='bold' />`.
- 
+
 ## 4.13.0
 
 ### Deprecated `Button` `appearance="pill"`
@@ -474,7 +546,7 @@ The “pill” appearance is deprecated due to confusion among designers and eng
 #### Migration steps
 Replace all usage of `Button` `appearance="pill"` with `appearance="default"` or use the `Link` component instead.
 
-### Deprecated `placeholder` prop in `Text`, `TextArea`, and `Number` 
+### Deprecated `placeholder` prop in `Text`, `TextArea`, and `Number`
 
 #### Change
 The `placeholder` prop in `Text`, `TextArea`, and `Number` is deprecated and will be removed from future major versions.
@@ -523,7 +595,7 @@ To keep the previous behavior, set `separateStackingContexts={false}`.
 ### Deprecated `RadioBar.Option`'s `icon` prop
 
 #### Change
-`RadioBar.Option`'s `icon` prop is deprecated and will be removed in a future major version. 
+`RadioBar.Option`'s `icon` prop is deprecated and will be removed in a future major version.
 
 #### Context
 The `RadioBar.Option` icon should not be used due to misalignment with `Text`.
@@ -536,13 +608,13 @@ Replace all usage of `RadioBar.Option`'s `icon` prop with `startAdornment` and/o
 ### Deprecated `Message` `appearance="banner"`
 
 #### Change
-`Message`’s `appearance="banner"` option is deprecated and will be removed in a future major version. 
+`Message`’s `appearance="banner"` option is deprecated and will be removed in a future major version.
 
 #### Context
-Please use `MessageBar` instead of `Message` with `appearance="banner"`. 
+Please use `MessageBar` instead of `Message` with `appearance="banner"`.
 
 Use `MessageBar` for:
-- System-level messages (such as expired accounts, server outages, account status, etc). 
+- System-level messages (such as expired accounts, server outages, account status, etc).
 - Information, warning, error, or success notifications
 
 Use `Message` or another component for:
@@ -557,7 +629,7 @@ Replace all usage of `Message`’s `appearance="banner"` option to `MessageBar`.
 `Message.Link` is deprecated and will be removed in a future major version.
 
 ### Context
-`MessageBar` now applies the necessary styles to `Link`. 
+`MessageBar` now applies the necessary styles to `Link`.
 
 #### Migration steps
 Replace all usage of `Message.Link` with the `Link` component as a child of the `MessageBar` component. See entries above or our docs for more information on `MessageBar`.
@@ -573,7 +645,7 @@ The `useSyntheticPlaceholder` prop in `Text` and `Number` is deprecated and will
 The `useSyntheticPlaceholder` prop is not needed because we no longer support IE11.
 
 #### Migration steps
-Remove the `useSyntheticPlaceholder` prop. 
+Remove the `useSyntheticPlaceholder` prop.
 
 ### Deprecated `Monogram` `size="xlarge"`
 
@@ -594,7 +666,7 @@ Replace all usage of `xlarge` as the value for `Monogram`'s `size` prop with the
 `Accordion` no longer supports `collapseAll` prop and all panels are allowed to collapse by default.
 
 #### Context
-The user needs to be able to skip over any section with `tab`, which is not possible when the first one is open. This prop is no longer supported due to accessibility issues when set to `false`. 
+The user needs to be able to skip over any section with `tab`, which is not possible when the first one is open. This prop is no longer supported due to accessibility issues when set to `false`.
 
 #### Migration steps
 Remove all usage of `Accordion` `collapseAll`.
@@ -602,10 +674,10 @@ Remove all usage of `Accordion` `collapseAll`.
 ### `File` now supports `fullscreen` prop instead of `size="large"`.
 
 #### Change
-`File`’s `size` prop has been removed. Instead, use the `fullscreen` prop. 
+`File`’s `size` prop has been removed. Instead, use the `fullscreen` prop.
 
 #### Context
-If `fullscreen` prop is set, there can only be one `File` component on the page as it will take all files dropped on the page. 
+If `fullscreen` prop is set, there can only be one `File` component on the page as it will take all files dropped on the page.
 
 #### Migration steps
 Replace all usage of `size="large"` with `fullscreen` prop. Remove all other usage of `File` `size`.
@@ -627,7 +699,7 @@ Ensure the toggle `ref` is an `HTMLElement`, `Clickable`, `Button`, or `Link`.
 `Popover`’s `pointerEvents` prop has been removed.
 
 #### Context
-Previously, `Tooltip` closed as soon as a user stopped hovering over the toggle. To allow the `Tooltip` to remain open when hovering/focusing on the toggle or the content area, the `Popover`’s `pointerEvent` prop has been removed. `Tooltip` now has two props: `possibleOpenReasons` and `possibleCloseReasons`, which provide more control over when the `Tooltip` can be opened and closed. 
+Previously, `Tooltip` closed as soon as a user stopped hovering over the toggle. To allow the `Tooltip` to remain open when hovering/focusing on the toggle or the content area, the `Popover`’s `pointerEvent` prop has been removed. `Tooltip` now has two props: `possibleOpenReasons` and `possibleCloseReasons`, which provide more control over when the `Tooltip` can be opened and closed.
 
 #### Migration steps
 Replace all usage of `Popover`’s `pointerEvents` prop with `possibleOpenReasons` and `possibleCloseReasons`.
@@ -642,12 +714,12 @@ Replace all usage of `Popover`’s `pointerEvents` prop with `possibleOpenReason
 
 #### Context
 
-`Text`'s `appearance` prop allowed the values "default" and "search". 
-With the new `Search` component optimized for user interaction, Text's `appearance` prop has become unnecessary. 
+`Text`'s `appearance` prop allowed the values "default" and "search".
+With the new `Search` component optimized for user interaction, Text's `appearance` prop has become unnecessary.
 
 #### Migration steps
 
-Replace all usage of `Text`'s `appearance="search"` value with the `Search` component. Remove all usage of `Text`'s `appearance="default"` value. 
+Replace all usage of `Text`'s `appearance="search"` value with the `Search` component. Remove all usage of `Text`'s `appearance="default"` value.
 
 ## 4.36.0
 
@@ -663,5 +735,18 @@ The `size` prop currently does not do anything in `ComboBox`, `ControlGroup`, or
 
 #### Migration steps
 
-Remove all usage of `ComboBox`, `ControlGroup`, and `StaticContent`'s `size` prop. To change the size of components, use the `SplunkThemeProvider`'s `density` prop. 
+Remove all usage of `ComboBox`, `ControlGroup`, and `StaticContent`'s `size` prop. To change the size of components, use the `SplunkThemeProvider`'s `density` prop.
+
+## 4.39.0
+
+### Deprecated `Menu.Item`'s `icon` prop
+
+#### Change
+`Menu.Item`'s `icon` prop is deprecated and will be removed in a future major version.
+
+#### Context
+The `Menu.Item` icon should not be used as `Menu.Item` as that restricted the location of the icon and it is now possible to place an adornment at the start or the end of the `Menu.Item` content.
+
+#### Migration steps
+Replace all usage of `Menu.Item`'s `icon` prop with `startAdornment` and/or `endAdornment`.