# Migration

This document lists migration guidance for new features and breaking changes.

## 5.10.0

### Deprecated `ColumnLayout`

#### Change
`ColumnLayout` has been deprecated and will be removed in a future major version.

#### Context
`ColumnLayout` is a flexbox-based component that provides a 12-column grid abstraction. It exists for historical and backwards-compatibility reasons. We recommend migrating to CSS `grid` directly, which provides better styling control, supports intrinsic sizing, allows the use of design tokens for spacing, and avoids the overhead of a React component.

#### Migration steps
If you aren't familiar with CSS grid layout, explore some of the following resources before migrating:
- [CSS grid layout guide](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout)
- [Basic concepts of grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout/Basic_concepts)
- [CSS grid property reference](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/grid)

Replace `ColumnLayout`, `ColumnLayout.Row`, and `ColumnLayout.Column` with CSS `grid`. Use `gridColumn` with `span` for column widths, and replace the `gutter` prop with `gap`:

```jsx
// Before
<ColumnLayout gutter={8}>
    <ColumnLayout.Row>
        <ColumnLayout.Column span={3}>Column</ColumnLayout.Column>
        <ColumnLayout.Column span={9}>Content</ColumnLayout.Column>
    </ColumnLayout.Row>
</ColumnLayout>

// After
const StyledGrid = styled.div`
    display: grid;
    grid-template-columns: repeat(12, 1fr);
    gap: ${variables.spacingSmall};
`;

<StyledGrid>
    <div style={{ gridColumn: 'span 3' }}>Column</div>
    <div style={{ gridColumn: 'span 9' }}>Content</div>
</StyledGrid>
```

## 5.5.0

### Deprecated `Switch`'s `selectedLabel`, `someSelectedLabel`, and `unselectedLabel` props

#### Change
`Switch`'s `selectedLabel`, `someSelectedLabel`, and `unselectedLabel` props have been deprecated and will be removed in the next major version.

#### Context
`Switch`'s `selectedLabel`, `someSelectedLabel`, and `unselectedLabel` props have low usage and the same behavior can be achieved in other ways.

#### Migration steps
* Remove all usage of `Switch`'s `selectedLabel`, `someSelectedLabel`, and `unselectedLabel` props.
* Change the content depending on the `selected` prop's value and do any of the following:
    * Set the `aria-label` prop to your content and pass the prop into `Switch`
    * Use the `ScreenReaderContent` component
    * Place content on screen

### Add new prop `horizontalOverflow` to `Table`

#### Change
* `Table` supports a new prop called `horizontalOverflow`.

#### Context
The `Table` component's default overflow behavior has changed between version v4 and v5:

- **v4**: When the `Table`'s container is smaller than the `Table` it will scroll horizontally. `HeadCell` content remains fully visible and `Cell` content wraps only at word breaks.
- **v5**: The `Table` has a responsive behavior. `HeadCell` content truncates when needed, `Cell` content wraps to fit available space, and horizontal scrolling occurs only when `Table`'s container is smaller than `Table`'s width. 

#### Migration Steps
* To restore v4 behavior, use `horizontalOverflow="scroll"` prop. This enables horizontal scrolling when `Table` has overflow, keeps `HeadCell` content fully visible, and limits `Cell` content wrapping to word breaks only.

## 5.3.0

### `Switch`'s `appearance="checkbox"` prop has been deprecated in favor of new `Checkbox` component.

#### Change
`Switch`'s `appearance="checkbox"` prop has been deprecated and will be removed in the next major version.

#### Context
The `Switch` component combines two different components - a checkbox and a toggle. While superficially similar in that they both provide a boolean control, they are semantically different controls.

* `appearance="toggle"` is semantically a button, and should have an immediate effect
* `appearance="checkbox"` is semantically a checkbox, and should not take effect until a form submission or similar action has been taken

Additionally, there are several properties (error, indeterminate state) that exist as props on `Switch` despite only being supported when `appearance="checkbox"`.

Given this, we are introducing a new `<Checkbox>` component that can replace `<Switch appearance="checkbox">`.

#### Migration steps
* Replace `<Switch appearance="checkbox">` with `<Checkbox />`, and update the following props:
    * replace `onClick` with `onChange`
      * note that `onChange` reports the new state of the `Checkbox`, whereas `onClick` reported the old state of the `Switch`
    * replace `toggleRef` with `inputRef`
    * replace `selected` with `checked`
    * replace `selected="some"` with `checked="indeterminate"`
    * replace `selectedLabel`, `someSelectedLabel`, or `unselectedLabel` with an `aria-label` that matches `checked`
        * consider whether or not these three props are necessary, and if a visible label can be used instead

## 5.0.0

### Component spacing

To unify the styling of components margin has been removed and components should not have any spacing outside of its border box.

#### Content components

Some components had `margin-bottom` by default: e.g. `Heading` or `Paragraph`. Although this could
simplify styling with text content, often it needed to be overridden when using these
components in an application. Additionally, it was not consistent which components
would have the additional spacing.

When spacing is needed in long-form text content the new `Prose` component can be used to add styling that optimizes for readability.

#### inline margin

Previously, certain components automatically applied a `margin-left` when siblings with other components (e.g., two `Button`s, or a `Text` and a `Button`). This behavior worked fine for basic use cases where no additional styling was needed for spacing.

However, it created issues in more complex layouts, especially with modern techniques like flex and grid, requiring developers to manually reset the margin. To be consistent with removing margin outside components' border box and encourage modern layout practices, this automatic margin has been removed. The `inline` attribute remains, and it still affects the display and width of certain components.

For spacing between components, use the new `Layout` component, which applies spacing without relying on margin. If you’re already using a wrapper, you can instead use `@splunk/themes/mixins/layout` to manage spacing, allowing you to remove previous margin overrides.

### Component font styles

#### New features and changes

-   The font size and line height no longer change with density (SUI-5508).
-   The default font-size in Enterprise Compact now is 14px (SUI-5508).

#### Migration steps for font-size, font-weight and font-family

```jsx
css`font-size: ${variables.fontSizeSmall}`
is equivalent to
css`font-size: ${mixins.typography({ size: 12 })}`

css`font-size: ${variables.fontWeightSemiBold}`
is equivalent to
css`font-weight: ${mixins.typography({ weight: 'semiBold' })}`

css`font-family: ${variables.sansFontFamily}`
is equivalent to
css`font-family: ${mixins.typography({ family: 'sansSerif' })}`

css`line-height: ${variables.lineHeight}`
is equivalent to
css`font-size: ${mixins.typography({ lineHeight: 20 })}`
```

### Monogram to Avatar

`Monogram` will be removed in a future major version. Use `Avatar` instead (SUI-5608).

#### New features and changes

-   `Avatar` supports images via `image` prop (SUI-3227).
-   `Avatar`'s `value` prop replaces `Monogram`'s `name` prop (SUI-5610).
-   `Avatar`'s `size` prop doesn't have an `"xlarge"` option (SUI-5518).
-   `Avatar`'s `size` prop supports `string` instead of `number` (SUI-5615).
-   `Avatar`'s `"medium"` size is `32px` and `large` size is `48px` (SUI-5615).
-   `Avatar` has the same sizes in Enterprise and Prisma theme (SUI-5617).
-   `Avatar` requires `label` prop (SUI-5611).
-   `Avatar`'s text color will change automatically depending on the background color to comply with accessibility contrast requirements (SUI-5614).
-   `Avatar`'s `backgroundColor` prop doesn't have a `"theme"` option (SUI-5614). No value for `backgroundColor` is needed for the default background colors.

#### Migration steps

###### `size` prop

```jsx
<Monogram size="medium" /> is equivalent to <Avatar size='large'/>
<Monogram size="large" /> is equivalent to <Avatar size='80px'/>
<Monogram size="xlarge" /> is equivalent to <Avatar size='144px'/>

Convert any usage of a number type to string type:
<Monogram size={40} /> is equivalent to <Avatar size='40px'/>
```

###### `name` prop

```jsx
<Monogram initials="A" name="Amelia" onClick={() => {}} />
is equivalent to
<Avatar initials="A" value="Amelia" onClick={() => {}}/>
```

### Change to `Modal.Header` icon

`Modal.Header`'s `icon` prop no longer requires `width="100%" height="100%"` to be set on the icon to render at the correct size (SUI-5931).

#### Migration steps

Remove `width="100%" height="100%"` from the icon.

### Change to `Modal` overlay click behavior

Modals no longer close when clicking on the overlay by default.

This change was made to improve accessibility and prevent accidental data loss.

#### Migration steps

First, evaluate whether enabling `closeOnClickAway` aligns with the [Modal usage guidelines](./Modal). If closing a modal by clicking outside of it is required, explicitly enable this behavior by setting `closeOnClickAway={true}` on `Modal`.

### Changes to `Modal` and `Modal.Header` `onRequestClose` prop

`Modal.Header` now uses the `onRequestClose` prop from `Modal` and no longer supports its own `onRequestClose`.
When the `Modal` is closed by clicking the "close" button in Modal.Header` the `reason` parameter will be `"clickCloseButton"` (SUI-5933).

For cases where `onRequestClose` was not set on `Modal.Header`, the "close" button can be hidden with the new `hideCloseButton` prop to maintain prior behavior.

#### Migration steps

If `onRequestClose` was set on `Modal.Header`, remove it and either add the `onRequestClose` to `Modal` or update it if it exists. If it's necessary to determine if the prop was called by the "close" button in `Modal.Header`, the `reason` parameter will be set to `"`clickCloseButton`" in those cases.
If `onRequestClose` was not set on `Modal.Header`, add the new `hideCloseButton` prop to maintain prior behavior.

### `JSONTree`'s `expandChildren` prop renamed to `defaultExpanded` and no longer affects node expansion behavior after the initial render.

#### Change

`JSONTree`'s `expandChildren` prop has been renamed to `defaultExpanded` and no longer affects node expansion behavior after the initial render.

#### Context

The old behavior of `JSONTree`'s `expandChildren` prop was to:
1. Start with all nodes expanded.
2. Always expand all descendant nodes when a node is expanded.

Now `expandChildren` has been renamed to `defaultExpanded` and the behavior of `defaultExpanded` is to:
1. Start with all nodes expanded. This behavior remains the same as `expandChildren`.
2. Subsequent node expansions are not affected by `defaultExpanded` - they only expand one level of nodes. This behavior is different from `expandChildren`'s old behavior.

This change in behavior was made because it was likely not a desired behavior and unintuitive that `expandChildren` would always expand all descendant nodes.
Then `expandChildren` was renamed to `defaultExpanded` to make it clear it does not affect node expansion behavior after the initial render.

#### Migration steps

Replace all usage of `JSONTree`'s `expandChildren` prop with `defaultExpanded`.
To expand all descendant nodes when a node is expanded, use the `expandChildrenOnShiftKey` prop instead.

### `ComboBox`, `Date`, `Multiselect`, `Number`, `Search`, `Select`, and `Text` no longer use the TypeScript `HTMLTextAreaElement` type in event handlers and refs

#### Change

`ComboBox`, `Date`, `Multiselect`, `Number`, `Search`, `Select`, and `Text` no longer use the TypeScript `HTMLTextAreaElement` type in event handlers.
`Number` and `Text` no longer use the TypeScript `HTMLTextAreaElement` type for the `inputRef` prop (SUI-6206).

#### Context

`Text`'s `multiline` prop was removed. With this change, it is no longer necessary for `Text` and components that use `Text` to
have props that include the TypeScript `HTMLTextAreaElement` type.

#### Migration steps
* Change the callbacks passed into the following props to use an event type that doesn't include `HTMLTextAreaElement`:
    * `ComboBox`
        * `onBlur`
        * `onChange`
        * `onFocus`
    * `Date`
        * `onBlur`
        * `onFocus`
    * `Multiselect`
        * `onFilterChange`
    * `Number`
        * `onBlur`
        * `onChange`
        * `onFocus`
    * `Search`
        * `onBlur`
        * `onChange`
        * `onFocus`
    * `Select`
        * `onFilterChange`
    * `Text`
        * `onBlur`
        * `onClick`
        * `onChange`
        * `onFocus`
        * `onKeyDown`
        * `onSelect`
* Change any refs passed into `Text` and `Number`'s `inputRef` prop with the TypeScript `HTMLTextAreaElement` type to be of `HTMLInputElement` type instead.

### `Text`, `Date`, and `Number` `onClick` prop API changes

#### Change
- `Text`'s `onInputClick` prop has been renamed to `onClick`.
- `Date`'s `onClick` prop now uses Typescript `HTMLInputElement` type.
- `Number` supports new `onClick` prop with TypeScript `HTMLInputElement` type.

#### Context

`Text`'s `onClick` prop was applied to the wrapping element rather than the `input` element itself.
This caused difficulty disambiguating clicks on the `input` from clicks on other parts of the component, such as adornments.
To provide a temporary solution without breaking changes, an `onInputClick` prop was added for clicks on the `input` itself.
In 5.0, we're fixing the issue and removing the workaround, so `onClick` will now be applied directly to the `input` element,
which will result in a change to the TypeScript types.
`Date` and `Number` components will leverage the new callback, so their types will change to match.

#### Migration steps

- Replace all usage of `Text`'s `onInputClick` prop with `onClick`.
- Change callbacks passed to `Date`'s `onClick` prop to use an event with the TypeScript `HTMLInputElement` type.
- Change callbacks passed to `Number`'s `onClick` prop to use an event with the TypeScript `HTMLInputElement` type.

### `Collapsible Panel`, `Color`, `ControlGroup`, `Dropdown`, `Image`, `Link `, `Menu`, `Modal`, `Switch`, and `Text` converted to functional components

#### Change
`Collapsible Panel`, `Color`, `ControlGroup`, `File`, `Image`, `Link `, `Menu`, `Modal`, `Select.Option`, `Slider`, `SlidingPanel.Panel`, `Switch`, `Table.HeadDropdownCell`, and `Text` converted from class to functional components.

#### Context
React recommends defining components as functions instead of classes. Functional components don't have `ref` support.
Components that formerly supported class focus methods (`Color`, `Link`, `Menu`, `Number`, `Select.Option`, `Switch`, `TabBar.Tab`, `Table.HeadDropdownCell`, `Text`) no longer do so.

#### Migration steps
- Convert all usage of `ref` to `elementRef`.
- For `Number` and `Text`: Replace all usage of the class `focus` method with passing a `ref` to the `inputRef` prop and calling `inputRef.current.focus()`.
- For `Button`, `Color`, `Link`, `Menu`, `Multiselect.Option`, `Select.Option`, `SplitButton.Item`, and `TabBar.Tab`: Replace all usage of the class `focus` method with passing a `ref` to the `elementRef` prop and calling `elementRef.current.focus()`.
- For `Table.HeadDropdownCell`: Replace all usage of the class `focus` method with passing a `ref` to the `buttonRef` prop and calling `buttonRef.current.focus()`.
- For `Switch`: Replace all usage of the class `focus` method with passing a `ref` to the `toggleRef` prop and calling `toggleRef.current.focus()`.
- For `Slider`: Replace all usage of the class `focus` method with passing a `ref` to the `thumbRef` prop and calling `thumbRef.current.focus()`.
- For `Dropdown`: Replace all usage of the class `focus` method with passing `focus()` on the element passed to `toggle`.

### `Table.HeadDropdownCell`'s `defaultPlacement` prop has been removed

#### Change
`Table.HeadDropdownCell` no longer accepts a `defaultPlacement` prop.

#### Context
Previously `Table.HeadDropdownCell` accepted (and passed down to its `Popover` instance) a `defaultPlacement` prop. To avoid layout and positioning issues this is no longer able to be overridden in favor of only supporting `bottom` placement of the `Table.HeadDropdownCell`'s `Popover`.

#### Migration steps
- Remove any passing of `defaultPlacement` prop to `Table.HeadDropdownCell`

### Deprecated `RadioList`'s `direction` prop

#### Change
`RadioList`'s `direction` prop has been deprecated and will be removed in the next major version.

#### Context
When having a single select option list displayed horizontally, `RadioBar` provides a better user interface and experience.

#### Migration steps
- Replace any instances of `RadioList` that use `direction="row"` with `RadioBar`.

### Deprecated `Card`'s `selected` prop

#### Change
`Card`'s `selected` prop has been deprecated and will be removed in the next major version.

#### Context
There was a concept of a `Card` being selected (driven by the `selected` prop) but it failed to meet proper accessibility standards. This was due to the individual `Card` component not having the proper context of how it was being used to correctly apply aria attributes such as `aria-role` and `aria-checked`.

#### Migration steps
- General guidance remains to prefer more purpose specific input components such as `Multiselect`, `RadioList`, or `Switch` over using `Card` in an input context due to the accessibility considerations they contain. If possible consider removing any selectable `Card` usage and migrating to those components instead.
- If continuing to use `Card` as an input, remove any passing of the `selected` prop to `Card` and provide selected state accessibility affordance instead by using a radio button or checkbox in the `Card` such as in the `Card.Header`. Be sure to handle aria attributes such as [aria-role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) and [aria-checked](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) as your use case may require.

### Deprecated `Select`'s `appearance="link"` value

#### Change
`Select`'s `appearance="link"` value has been deprecated and will be removed in the next major version.

#### Context
Using a `Select` with `appearance="link"` can be misleading because links are primarily used for navigation, while a `Select` is designed for making a choice, which involves a different interaction model.
This difference can cause confusion and conflict with accessibility expectations, as dropdowns have different interaction requirements compared to inline links.

#### Migration steps
- Replace Select with appearance="link" by using either appearance="default" or appearance="subtle", depending on design requirements.

### Deprecated `TabBar` and `TabLayout`'s `iconPosition` prop

#### Change
`TabBar` and `TabLayouts`'s `iconPosition` prop is deprecated and will be removed in the next major version.

#### Context
`TabBar`'s `iconPosition="above"` value is deprecated because stacking an icon above text creates a vertical layout that’s harder to scan quickly, especially when multiple `Tab`s are present. The added vertical space can make the `TabBar` taller and more visually crowded, reducing the clarity and simplicity that `TabBar`s are supposed to offer.
Due to this `TabBar`'s `iconPosition` would only have the value of `left` remaining thus there is no longer a need for the `iconPosition` prop to specify icon positioning. Because `TabLayout` uses `TabBar` its matching prop is deprecated as well.

#### Migration steps
- Remove any setting of `TabBar` or `TabLayout`'s `iconPosition` prop and instead allow its default behavior of left icon positioning to take effect when icons are passed.

### Deprecated `Multiselect`'s `selectAllAppearance="buttongroup"` value

#### Change
`Multiselect`'s `"buttongroup"` value of the `selectAllAppearance` prop has been deprecated and will be removed in the next major version.

#### Context
Using `Multiselect`'s `selectAllAppearance="checkbox"` will fix accessibility issue by making it easier to toggle between "select all" and "select none" with one less tab stop.

#### Migration steps
- Replace `Mulitselect`'s `selectAllAppearance="buttongroup"` with `selectAllAppearance="checkbox"`.

### New implementation for `Markdown`

#### Change
The `commonmark-react-markdown` library has been replaced with `react-markdown` for rendering markdown.

#### Context
`commonmark-react-markdown` does not support GitHub flavored markdown (GFM) and is no longer actively-maintained. `react-markdown` supports GFM via plugins. In addition to other features, this primarily enables rendering tables within markdown.

`react-markdown` ships as ESM which can cause issues with test runners like `jest`.

#### Migration steps
- If using `jest`, add the following to your `jest.config` file:
    ```
        moduleNameMapper: {
            'react-markdown': '<rootDir>../../node_modules/react-markdown/react-markdown.min.js',
        },
    ```


### New `Modal.Footer` layout

#### Change

`Modal.Footer` has a new `layout` prop to control the layout and styling of children.

#### Context

Common use cases for content within Modal.Footer include:
- A single Button
- A pair of Buttons
- Documentation links
- Controls (e.g., Checkbox, Switch)
- Wizards
- Static content
- Combinations of the above

 In 4.x versions, `Modal.Footer` handled styling for a single `Button` or pair of `Button`s correctly. Other use cases required custom styling. In 5.x `Button`'s no longer have margin from sibling `[data-inline]` elements, which would break the use cases previously supported by `Modal.Footer` in 4.x.

To simplify the implementation and ensure consistent design for these common use cases, the default styling for `Modal.Footer` has been updated. Now, these common use cases will display correctly without requiring additional styling.

A new prop `layout` has been added to `Modal.Footer` to control styling children.
The default value, `auto`, uses the updated styling, while `layout="none"` will revert to the 4.x styling, in cases where the new layout is incorrect.

#### Migration steps
**For a single Button or pair of Buttons**: No migration is necessary—existing code should work as before.

**For other common use cases (e.g., Checkbox, static content, wizards)**: Any custom layout or styling previously applied may no longer be needed and can be removed.

**For custom layouts**: If a custom layout is still required, revert to the 4.x styling by setting the `layout="none"` prop and/or refactor styles to work with the `auto` styling.


### `Button`, `Clickable', `CollapsiblePanel`, and `Menu.Item`'s default `disabled` behavior is now `dimmed`

#### Change

`Button`, `Clickable`, `CollapsiblePanel`, and `Menu.Item` components with the `disabled` prop will, by default, exhibit the `dimmed` behavior.
To revert to the original behavior (where the component cannot receive focus), set disabled="disabled".

For testing, a new `data-test-disabled` test hook has been added.

#### Context

Whenever possible `disabled` components should be avoided.

A `disabled="disabled"` component is less accessible, since it is less discoverable to keyboard users by not receiving focus. Additionally, `Tooltip`s associated with these components become inaccessible, since the component cannot receive focus to activate the `Tooltip`.

`disabled="dimmed"` was introduced in v4.25.0 to provide a more inclusive approach to disabling components. Dimmed components remain focusable, are semantically marked as disabled, and still prevent the user from activating the component.

By using the `"dimmed"` state as the default, the user experience of these components is more inclusive.

#### Migration Steps

###### Validate new default `dimmed` behavior

Validate your application and components work as expected with the new default behavior.
If the component can benefit from being more discoverable and accessible, leave the `disabled` prop as is.

###### Use `disabled="disabled"` sparingly
Assess whether you want to retain the button’s original disabled behavior (non-focusable, non-interactive, etc.). If that's the case, set disabled="disabled".

###### Updating tests
When testing, it is recommended to test the user interaction rather than component's state or props (e.g. test that the user cannot activate the control).

Matchers like `toBeDisabled()` will no longer pass when using `disabled` or `disabled="dimmed"`.
If it is necessary to test the components state, use the new test hook state attribute.

* For `dimmed` components, replace `expect(button).toBeDisabled()` with:
```
expect(button).toHaveAttribute('data-test-disabled');
```

* For `disabled="disabled" components, `toBeDisabled` will continue to work.


### `Slider`'s test hook `[data-test="handle"]` renamed to `[data-test="thumb"]`

#### Change

`Slider`'s test hook `[data-test="handle"]` has been renamed to `[data-test="thumb"]`.

#### Context

`Slider`'s draggable control has been renamed from "handle" to "thumb" to better align with
the more commonly used name for this element (e.g. ARIA refers to it as "thumb"). Also,
the name "handle" can be misleading, as it could be confused with event handlers, etc.

#### Migration steps

Replace all usage of `Slider`'s test hook `[data-test="handle"]` with `[data-test="thumb"]`.

### `Dropdown`'s `toggle` prop now requires an HTML Element or `React.forwardRef`

#### Change

`Dropdown`'s `toggle` prop no longer accepts React class components or functional components without `React.forwardRef`.
Components passed to `Dropdown`'s `toggle` prop must accept a `ref` that returns an HTML element.

#### Context

`Dropdown` previously leveraged `Popover`s usage of `findDOMNode` to find the underlying HTML element for a React component.
Given that `findDOMNode` is deprecated and scheduled for removal in React 19, we're removing our usages of it.

#### Migration Steps

If you are using `Button`, `Clickable`, or  `Link` components as the `toggle`, no migration is necessary.

Otherwise:
- Convert any components passed to `toggle` to `React.forwardRef` components that forward the ref to an HTML element.
    - If you previously passed a component wrapped in `Tooltip` to `toggle`, you need to forward the ref to the wrapped component.
- Consider using `react-ui`'s `Button`, `Clickable`, or  `Link` components for the `toggle` prop.
- See the React docs for alternatives to `findDOMNode` usage: https://18.react.dev/reference/react-dom/findDOMNode#alternatives

### `Popover`'s `anchor` prop now requires an HTML element

#### Change

`Popover`'s `anchor` prop now requires a ref to a HTML element and no longer accepts refs to React class component instances.

#### Context

`Popover`s has previously used `findDOMNode` to find the underlying HTML element for a React component.
Given that `findDOMNode` is deprecated and scheduled for removal in React 19, we're removing our usages of it.

#### Migration Steps

Pass a `ref` that refers to an HTML Element to the `anchor` prop.

- For `react-ui` components, use `elementRef` to get a `ref` to the underlying HTML element.
- For custom components, use `forwardRef`.
- See the React docs for alternatives to `findDOMNode` usage: https://18.react.dev/reference/react-dom/findDOMNode#alternatives


### `Switch`'s test hook `[data-test="button"]` renamed to `[data-test="toggle"]`

#### Change

`Switch`'s test hook `[data-test="button"]` has been renamed to `[data-test="toggle"]`.

#### Context

`Switch`'s underlying toggle element has been renamed from "button" to "toggle" to be less generic and describe its function of switching between states.

#### Migration steps

Replace all usage of `Switch`'s test hook `[data-test="button"]` with `[data-test="toggle"]`.

### `TabBar`'s `tabWidth` prop has been removed

#### Change
`TabBar`'s `tabWidth` prop has been removed. A new `maxTabWidth` prop has been added to support some use cases previously supported by the `tabWidth` prop.

#### Context
In previous versions `TabBar.Tab`s could have their width statically set by passing the `tabWidth` prop to the `TabBar`. However, the updated design for `TabBar` has responsive widths for `TabBar.Tab`s so setting a static tab width is no longer supported.

#### Migration steps
There are were two possible use cases for `tabWidth`:

1) If you desire each `Tab` to not exceed a certain width, use `maxTabWidth`.
2) If you desire each `Tab` to be the exact same width, we recommend against this - please reach out to us if you have a specific use case in mind.

### Deprecated `Card.Header`'s `anchor` prop

#### Change

`Card.Header`'s `anchor` prop has been deprecated and will be removed in the next major version.

#### Context

Card titles need to be headings when there is content underneath to satisfy accessibility requirement WCAG 1.3.1.
The recommended way to do this is to pass the `Heading` component into the `title` prop.

The anchor prop leads to visual issues when non-text content (such as a Heading is passed to the `title` attribute).
To avoid this and because the functionality of the `anchor` prop can be achieved by passing the `Anchor` component to the `title` prop,
we have deprecated the `anchor` prop.

#### Migration steps
Replace all usage of the `anchor` prop with passing in the `Anchor` component to the `title` prop:
```jsx
    <Card.Header title={<Anchor name="Title">Title</Anchor>} />
```

### Deprecated `Popover`'s `"inverted"` value of the `appearance` prop

#### Change

`Popover`'s `"inverted"` value of the `appearance` prop has been deprecated and will be removed in the next major version.

#### Context

The inverted appearance was deprecated to ensure the Popover background aligns with the color scheme, i.e. Popover should be light in light mode and dark in dark mode.

#### Migration steps
Replace all usage of Popover's `appearance="inverted"` with `appearance="normal"` (default).
If teams need to keep inverted Popovers they can use `backgroundColorFloating` and `contentColorInverted`. Otherwise Popover uses `backgroundColorPopup`.
```jsx
const StyledContent = styled.div`
    background-color: ${variables.backgroundColorFloating};
    color: ${variables.contentColorInverted};
`;

return (
    <Popover>
        <StyledContent>Popover content</StyledContent>
    </Popover>
)
```

### `Button`'s `label` prop no longer sets `label` attribute

#### Change
`Button`'s `label` prop no longer sets HTML attribute `label` on the underlying button element.

#### Context
In previous versions, the `label` prop, which sets the text on the Button, was also passed as a `label` HTML attribute which is invalid HTML for a `<button>`. This has been removed.

#### Migration steps
Replace usages of `label` selector in tests with a different suitable query e.g. replace `querySelector('[label="Save"]')` with `getByText('Save')`.

### `Color`'s test hook `[data-test="color"]` moved to root and `[data-test="toggle-swatch"]` added to toggle swatch

#### Change

`Color`'s test hook `[data-test="color"]` has been moved to the root `div` element and a new test hook `[data-test="toggle-swatch"]` has been added to the toggle swatch.

#### Context

`Color`'s test hook `[data-test="color"]` was incorrectly documented as the root of the component but was actually set on the toggle swatch.

#### Migration steps
If the test hook needs to be on the root element of `Color`, use `[data-test="color"]`.
If the test hook was being used to interact with the toggle swatch, replace usage of `[data-test="color"]` with `[data-test="toggle-swatch"]`.

### All components that previously used `KeyboardEvent`'s deprecated `keyCode` property now use `KeyboardEvent`'s `key` property.

#### Change

Switched all components that previously used `KeyboardEvent`'s deprecated `keyCode` property to use its `key` property instead.

#### Context

Since current testing library tooling (such as `userEvent`) no longer provides a keyCode along with synthetic keyboard events,
upgrading testing libaries could cause tests to break. By removing the usage of `keyCode` in our codebase, this enables testing libary upgrades.

#### Migration steps

Use `KeyboardEvent`'s `key` property instead `keyCode` property to identify key presses.

## 4.44.0

### `ButtonGroup` role changed to `group`

#### Change

`ButtonGroup`'s `role` has changed from `menubar` to `group`.
Child `Button`'s `role`s have changed from `menuitem` to `button`.

#### Context

`ButtonGroup` did not implement the correct keyboard behavior for a menu bar.
This created an unexpected user experience for keyboard and screen reader users.

#### Migration steps

If `role="group"` is not desired:
* consider using `RadioBar` which supports `role="menubar"`
* implement either the [Menubar](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) or [Toolbar](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) pattern according to WCAG guidelines using `ButtonGroup`
* contact the Design System team to make a feature request based on your use case.

## 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.

### Deprecated `TabBar` and `TabLayout`'s `iconSize` prop

#### Context

The `iconSize` prop has two major issues:

* Despite its name, it controls both size and position, which is both confusing to users and makes it difficult to control those independently.
* It does not correctly set the icon size for the new icons introduced in `@splunk/react-icons@4`.

To eliminate these issues, we have deprecated the `iconSize` prop.

#### Migration steps

Remove usages of the `iconSize` prop.

* Icon position can now be controlled with the new `iconPosition` prop.
* Icon size can be set using `@splunk/react-icons` APIs.
* If you are using the new icons in `react-icons@4`, you can set size with the `height` and `width` props.
* If you are using `react-icons@3` or using the `/enterprise` path in `react-icons@4`,
    the `size` prop can be set to `"18px"` to match `iconSize="small"` or `"36px"` to match `iconSize="large"`.

## 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`.

### 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 existence 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:

* If you were using `appearance="navigation"`, that is the default appearance and removing the prop will have no effect.
* 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.36.0

### Deprecated `ComboBox`, `ControlGroup`, and `StaticContent`'s `size` prop

#### Change

`ComboBox`, `ControlGroup`, and `StaticContent`'s `size` prop has been deprecated and will be removed in the next major version.

#### Context

The `size` prop currently does not do anything in `ComboBox`, `ControlGroup`, or `StaticContent`, so it will be removed in the next major version.

#### 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.

## 4.35.0

### Deprecated `Menu`'s `retainFocus` prop

#### Change

`Menu`'s `retainFocus` prop is deprecated and will be removed in the next major version.

#### Context

To provide more control over the focus behavior of `Menu`, including the option to opt out of focus management, a new `focusMode` prop has been introduced with the following values:
- `never`: The menu will never take focus, and the active menu item will not have a focus-like appearance.
- `normal`: Opts out of focus management. The menu and its children follow the normal focus order of DOM without any interference (no loop, no arrow keys, multiple tab stops).
- `roving` (original `retainFocus={false}`): Does not retain focus inside the menu. There is one tab stop of menu. Uses up/down arrow keys to navigate and loop inside the menu.

The original `retainFocus={true}` is no longer supported due to its poor user experience and accessibility issues:
* If the Menu is used standalone, it traps the tab navigation within the Menu, preventing the user from accessing the next element via keyboard navigation.
* If the Menu is used in a `Dropdown`, it creates multiple tab stops, making navigation inefficient.

#### Migration steps

* Replace `retainFocus={false}` with `focusMode="roving"`.
* If `retainFocus={true}` was used, replace it with `focusMode="roving"`. Additionally, convert the corresponding tests with multiple tabs to use arrow key navigation.

## 4.34.0

### Deprecated `Select`'s `appearance` values of `"flat"`, `"pill"`, and `"toggle"`

#### Change

`Select`'s `appearance` prop's `"flat"`, `"pill"`, and `"toggle"` values are deprecated and will be removed in the next major version.

#### Context

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.

#### Migration steps

For Enterprise themes:
* the `"pill"` value can be replaced with `"subtle"` with no other changes.

For Prisma themes:
* the `"flat"` appearance can be replaced with `"subtle"`.
* the `"toggle"` appearance can be replaced with `"default"`.

### Improved `Card.Header` accessibility when rendering actions

#### Change

* New `actions` prop to render card actions.
* Default to rendering the container element as an `article` tag instead of a `div`.
* New `tag` prop to control the HTML tag used for `Card`'s container element.

#### Context

Cards rendered the `secondaryActions` button with the same label -- "Actions".
This would create an ambiguous label (especially when multiple cards are rendered) which may be confusing non-visual users.

The new `actions` prop provides full control over the rendering of the actions to make sure the secondary actions button name can be made unique and not ambiguous for assistive technology users.

Cards used a `div` as the container element which did not provide any semantic grouping of the content.
The new `article` container element provides semantic clarity, improves accessibility, and future-proofs the code, as it clearly denotes self-contained, independently distributable content, which `div` does not.

[MDN - Article Role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/article_role)

#### Migration steps

* Update `Card` to use the new `actions` prop instead of `secondaryActions` and add an unambiguous label for each action:

```jsx
<Card.Header title="My widget" actions={() => <>}>
    <HeaderActions>
        <Button icon={<Star/>} aria-label="Favorite My widget" />
        <Dropdown toggle={<ActionsSecondaryToggle content="More actions for My widget" />}>
            {actionsSecondaryMenuOne}
        </Dropdown>
    </HeaderActions>
</Card.Header>
```

## 4.33.0

### Deprecated `Button`'s `appearance` values of `"flat"`, `"pill"`, and `"toggle"`

#### Change

`Button`'s `appearance` prop's `"flat"`, `"pill"`, and `"toggle"` values are deprecated and will be removed in the next major version.

#### Context

The `"pill"` value for `appearance` was only supported in Enterprise themes, and the `"flat"` and `"toggle"` values were only supported in the Prisma themes.

As part of our effort to unify behaviors and APIs across themes, we are deprecating these appearances.

#### Migration steps

For Enterprise themes:
* the `"pill"` value can be replaced with `"subtle"` with no other changes.

For Prisma themes:
* the `"flat"` appearance can be replaced by `"secondary"` or `"subtle"` depending on the context in which it appears.
* the `"toggle"` appearance can be replaced with `"secondary"`.

### Deprecated `CollapsiblePanel`'s `titleWithActions` prop

#### Change

`CollapsiblePanel`'s `titleWithActions` prop has been deprecated and will be removed in the next major version.

#### 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,
while still providing the necessary interactivity.

#### Migration steps

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

### Deprecated `Text`'s `appearance` prop

#### Change

`Text`'s `appearance` prop has been deprecated and will be removed in the next major version.

#### 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.

#### Migration steps

Replace all usage of `Text`'s `appearance="search"` value with the `Search` component. Remove all usage of `Text`'s `appearance="default"` value.

### Deprecated `NavigationProvider`'s `prefix` prop

#### Change

`NavigationProvider`'s `prefix` prop has been deprecated and will be removed in the next major version.

#### Context

`NavigationProvider` allows global control over navigation via `Clickable`, `Link`, and any other component that implements the `to` prop.

One of the supported props is `prefix`, which allows links to be prefixed. This is helpful when your application might be nested inside a path; for example, it could be used to set the locale prefix to a URL.

The new `transformUrl` function can be used to replicate the functionality of `prefix` as well as perform other URL transformations. Therefore, `prefix` is being deprecated to avoid supporting multiple ways to modify the URL.

#### Migration steps

Replace `prefix` with the `transformUrl` function:

```jsx
    const prefix = '/my-prefix'

    <NavigationProvider transformUrl={(url, { isInternal, isRootRelative}) => {
        return isInternal && isRootRelative ? `${prefix}${url}` : url;
    }>
        <Link label="My page" to="/my-page" />
    </NavigationProvider>
```

Note: `prefix` only applied to internal, relative URLs, whereas `transformUrl` applies to all URLs.
However, `transformUrl` provides info about whether a URL is internal or relative that can be used to replicate this behavior.

## 4.29.0

### Deprecated `WaitSpinner`'s `children` prop

#### Change

`WaitSpinner`'s `children` prop has been deprecated and will be removed in the next major version.

#### Context

`WaitSpinner` does not support `children` and the prop was not applied in the render of the component. This was properly documented in the TypeScript API as: `children?: never;`. But due to a documentation bug this was not as explicit in the PropTypes documentation.

#### Migration steps

Remove all usage of `WaitSpinner`'s `children` prop. To render a message beside the wait spinner, render a sibling text element and set `screenReaderText` to `null`.

Example with a sibling text element:

```jsx
    <WaitSpinner screenReaderText={null} />
    <p>Loading logs</p>
```

## 4.27.0

### New `SingleOpenPanelGroup` API for `CollapsiblePanel`

#### Change
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.

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.

#### Migration steps
Replace usage of `Accordion` with the `SingleOpenPanelGroup` component exported from `CollapsiblePanel`. See the `SingleOpenPanelGroup` examples in `CollapsiblePanel`'s documentation.

### 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`.

#### Context
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.

## 4.26.0

### 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.

#### Context
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.

#### 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`.

For example, this code snippet:
```jsx
    const handleRequestClose = () => {
        setOpen(false);
        modalToggle?.current?.focus();
    };

    return (
        <>
            <Button onClick={handleRequestOpen} ref={modalToggle} label="Open modal" />
            <Modal onRequestClose={handleRequestClose} open={open}>
                <Modal.Body>Just a basic Modal.</Modal.Body>
            </Modal>
        </>
    );
```
can be converted to this code:
```jsx
    const handleRequestClose = () => {
        setOpen(false);
    };

    return (
        <>
            <Button onClick={handleRequestOpen} ref={modalToggle} label="Open modal" />
            <Modal returnFocus={modalToggle} onRequestClose={handleRequestClose} open={open}>
                <Modal.Body>Just a basic Modal.</Modal.Body>
            </Modal>
        </>
    );
```

## 4.23.0

### 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`.

#### 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
choosing to initially render the tree expanded.

#### Migration steps
Replace all usage of `JSONTree`'s `expandChildren="withShiftModifier"` value with the `expandChildrenOnShiftKey` prop.

## 4.18.0

### 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.

#### 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.
To keep the same style as `Heading`'s `level="s"` and `level="ss"` follow the below code:

*Enterprise*

`level="s"` styling:

```jsx
const StyledSHeading = styled(Heading)`
    font-weight: ${variables.fontWeightSemiBold};
    font-size: ${variables.fontSize}
    color: ${pick({
        dark: variables.gray80,
        light: variables.gray45,
    })};
`;

<StyledSHeading level={5} variant="title4"/>
```

`level="ss"` styling:

```jsx
const StyledSSHeading = styled(Heading)`
    color: ${pick({
        dark: variables.gray80,
        light: variables.gray45,
    })};
`;

<StyledSHeading level={6} variant="title5"/>
```

*Prisma*

`level="s"` styling:

```jsx
const StyledSHeading = styled(Heading)`
    font-size: ${variables.fontSize};
    color: ${variables.contentColorDefault};
`;

<StyledSHeading level={5} variant="title4"/>
```

`level="ss"` styling:

```jsx
No styling is needed.
<Heading level="ss"> is equivalent to <StyledSHeading level={6} variant="title5"/>
```

## 4.17.1

### `TextArea`'s `canClear` prop has been deprecated

#### Context
The clear button causes styling issues in TextArea that made it undesirable to support. When the scrollbar appears in a TextArea the clear button is positioned outside, which causes excessive negative space between the input border and scrollbar. This feature is supported in `Text` and `Search` but those components do not run into the styling issues because they do not have scrollbars.

Additionally, when entering text into a `TextArea` users can clear the contents using "Select all" via keyboard shortcut or mouse selection. These are natively supported actions and don't require a custom control. It was uncommon to see a clear button in other text areas when doing competitive analysis of other design systems.

#### 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:

1) Use the `endAdornment` prop:

```jsx
const [text, setText] = useState('I am clearable content.');
    const handleChange = (e, { value }) => {
        setText(value);
    };

    const handleClearClick = () => {
        setText('');
    };

    return (
        <TextArea
            onChange={handleChange}
            value={text}
            endAdornment={
                <StyledButton
                    appearance="secondary"
                    aria-label="Clear text"
                    icon={<Cross />}
                    onClick={handleClearClick}
                />
        />
    );
/>
```

2) Render a clear action outside of the TextArea:

```jsx
    const [text, setText] = useState('I am clearable content.');
    const handleChange = (e, { value }) => {
        setText(value);
    };

    const handleClearClick = () => {
        setText('');
    };

    return (
        <>
            <TextArea onChange={handleChange} value={text} />
            <StyledButton
                appearance="secondary"
                label="Clear text"
                icon={<Cross />}
                onClick={handleClearClick}
            />
        </>
    );
```


## 4.17.0

### `Typography` `weight` prop

#### Change
`Typography` no longer supports numerical values for `weight`.

#### Context
Supporting both numerical and keyword values creates confusion on which is correct to use.
Themes has new variables in version 4.17.0 that support all of the weight values in the design system.
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 [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS):

| Number | Keyword   |
| ------ | --------- |
|    300 | light     |
|    400 | normal    |
|    500 | semiBold  |
|    600 | semiBold  |
|    700 | bold      |
|    800 | extraBold |
|    900 | heavy     |

For example, convert `<Typography as="p" weight={700} />` to `<Typography as="p" weight='bold' />`.

## 4.13.0

### Deprecated `Button` `appearance="pill"`

#### Change
The `Button`'s "pill" appearance is deprecated and will be removed in a future major version.

#### Context
The “pill” appearance is deprecated due to confusion among designers and engineers between the different uses. To minimize confusion, there will be one primary `Button` rounded style.

#### 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`

#### Change
The `placeholder` prop in `Text`, `TextArea`, and `Number` is deprecated and will be removed from future major versions.

#### Context
The `placeholder` prop presents multiple visual and cognitive issues and should not be used.

#### Migration steps
The `placeholder` prop should be replaced with `ControlGroup`'s `label` or `help`. It is recommended to avoid using a placeholder, but if appropriate the `placeholder` HTML attribute is still supported.

## 4.12.0

### Deprecated `Text`'s `multiline`, `rowsMax`, and `rowsMin` props

#### Change
`Text`'s `multiline`, `rowsMax`, and `rowsMin` props have been deprecated. Instead use the new `TextArea` component for multiline text input.

#### Context
`Text` supported two modes -- single or multiline. Each modes had exclusive props: e.g. `maxRows` was only valid with the `multiline` prop.
This could be confusing and lead to unexpected or unsupported API combinations. Additionally, code in `Text` would only operate in one mode at a time. Moreover, `Text` with the `multiline` prop does not allow line breaks to be inserted with the “enter” key in some browsers.

By separating these modes, we have made it simpler and clearer to decide which component and props to use.
`Text` should be used for inline text input. `TextArea` should be used for long-form text input.
This aligns the components with the HTML spec and the Splunk Design System.

#### Migration steps
Replace instances of `Text` that use the `multiline` prop with the new `TextArea` component.

## 4.11.0

### New `separateStackingContexts` prop for `LayerStackGlobalProvider`

#### Change
A new prop, `separateStackingContexts`, has been added to `LayerStackGlobalProvider`. `separateStackingContexts` will default to false for backward compatibility but will later default to true in the next major version.

#### Context
Previously, dropdown menus were stacking on top of and blocking modals and modal-backdrops.

Now with `separateStackingContexts`, 'floating' items such as `Popover` and `Modal` will now be stacked in the order they are opened rather than a fixed order.

#### Migration steps
To keep the previous behavior, set `separateStackingContexts={false}`.

## 4.8.0

### Deprecated `RadioBar.Option`'s `icon` prop

#### Change
`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`.

#### Migration steps
Replace all usage of `RadioBar.Option`'s `icon` prop with `startAdornment` and/or `endAdornment`.

## 4.7.0

### Deprecated `Message` `appearance="banner"`

#### Change
`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"`.

Use `MessageBar` for:
- System-level messages (such as expired accounts, server outages, account status, etc).
- Information, warning, error, or success notifications

Use `Message` or another component for:
- Feedback of actions taken within the page (such as adding, deleting, or saving an item).

#### Migration steps
Replace all usage of `Message`’s `appearance="banner"` option to `MessageBar`.

### Deprecated `Message.Link`

#### Change
`Message.Link` is deprecated and will be removed in a future major version.

### Context
`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`.

## 4.5.0

### Deprecated `useSyntheticPlaceholder` prop in `Text` and `Number`

#### Change
The `useSyntheticPlaceholder` prop in `Text` and `Number` is deprecated and will be removed in a future major version.

#### Context
The `useSyntheticPlaceholder` prop is not needed because we no longer support IE11.

#### Migration steps
Remove the `useSyntheticPlaceholder` prop.

### Deprecated `Monogram` `size="xlarge"`

#### Change
`Monogram`'s `size="xlarge"` is deprecated and will be removed in a future major version.

#### Context
The `xlarge` option for `Monogram`'s `size` prop is deprecated to align with Figma.

#### Migration steps
Replace all usage of `xlarge` as the value for `Monogram`'s `size` prop with the values: `small`, `medium`, `large`, or a number.

## 4.0.0

### `Accordion` no longer supports `collapseAll` prop

#### Change
`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`.

#### Migration steps
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.

#### 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.

#### Migration steps
Replace all usage of `size="large"` with `fullscreen` prop. Remove all other usage of `File` `size`.

### `Dropdown` only supports HTMLElement toggle `ref`

#### Change
`Dropdown` no longer supports passing a toggle that returns a React component instance as `ref`.

#### Context
Previously, this was causing a warning in React strict mode.

#### Migration steps
Ensure the toggle `ref` is an `HTMLElement`, `Clickable`, `Button`, or `Link`.

### `Popover` no longer supports `pointerEvents` prop

#### Change
`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.

#### Migration steps
Replace all usage of `Popover`’s `pointerEvents` prop with `possibleOpenReasons` and `possibleCloseReasons`.