@splunk/react-ui 4.42.0 → 5.0.0-beta.2

package/MIGRATION.v5.mdx

@@ -0,0 +1,428 @@
+# Migration
+
+This document lists migration guidance for new features and breaking changes in v5.
+
+## 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.
+
+## 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`, `Select.Option`, 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`
+
+## Deprecation
+
+### 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.
+
+## Markdown users `react-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',
+        },
+    ```
+
+
+## `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"]`.