feat(menu-list-item): Details overlay (#68606)

Allow showing item details inside an overlay (`showDetailsInOverlay`) in
case we want to show more detailed information than just one line of
text.

- closes #68514

Author: ArthurKnaus

static/app/components/comboBox/comboBox.stories.tsx

@@ -1,16 +1,41 @@
 import {Fragment, useState} from 'react';
+import styled from '@emotion/styled';
 
 import type {ComboBoxOptionOrSection} from 'sentry/components/comboBox/types';
+import {KeyValueTable, KeyValueTableRow} from 'sentry/components/keyValueTable';
 import Matrix from 'sentry/components/stories/matrix';
 import SizingWindow from 'sentry/components/stories/sizingWindow';
 import storyBook from 'sentry/stories/storyBook';
+import {space} from 'sentry/styles/space';
 
 import {ComboBox} from './';
 
+const Divider = styled('hr')`
+  margin: ${space(1)} 0;
+  border: none;
+  border-top: 1px solid ${p => p.theme.innerBorder};
+`;
+
 const options: ComboBoxOptionOrSection<string>[] = [
   {label: 'Option One', value: 'opt_one'},
-  {label: 'Option Two', value: 'opt_two'},
-  {label: 'Option Three', value: 'opt_three'},
+  {label: 'Option Two', value: 'opt_two', details: 'This is a description'},
+  {
+    label: 'Option Three',
+    value: 'opt_three',
+    details: (
+      <Fragment>
+        <strong>{'Option Three (deprecated)'}</strong>
+        <Divider />
+        This is a description using JSX.
+        <Divider />
+        <KeyValueTable>
+          <KeyValueTableRow keyName="Coffee" value="Black hot drink" />
+          <KeyValueTableRow keyName="Milk" value="White cold drink" />
+        </KeyValueTable>
+      </Fragment>
+    ),
+    showDetailsInOverlay: true,
+  },
   {label: 'Disabled', value: 'opt_dis', disabled: true},
   {label: 'Option Four', textValue: 'included in search', value: 'opt_four'},
   {

static/app/components/compactSelect/listBox/option.tsx

@@ -33,6 +33,7 @@ export function ListBoxOption({item, listState, size}: ListBoxOptionProps) {
     tooltip,
     tooltipOptions,
     selectionMode,
+    showDetailsInOverlay,
   } = item.props;
   const multiple = selectionMode
     ? selectionMode === 'multiple'
@@ -97,6 +98,7 @@ export function ListBoxOption({item, listState, size}: ListBoxOptionProps) {
       labelProps={labelPropsMemo}
       leadingItems={leadingItemsMemo}
       trailingItems={trailingItems}
+      showDetailsInOverlay={showDetailsInOverlay}
       tooltip={tooltip}
       tooltipOptions={tooltipOptions}
       data-test-id={item.key}

static/app/components/menuListItem.tsx

@@ -1,13 +1,17 @@
-import {forwardRef as reactForwardRef, memo, useMemo} from 'react';
+import {forwardRef as reactForwardRef, memo, useMemo, useRef, useState} from 'react';
+import {createPortal} from 'react-dom';
+import {usePopper} from 'react-popper';
 import isPropValid from '@emotion/is-prop-valid';
-import type {Theme} from '@emotion/react';
+import {type Theme, useTheme} from '@emotion/react';
 import styled from '@emotion/styled';
 
 import InteractionStateLayer from 'sentry/components/interactionStateLayer';
+import {Overlay, PositionWrapper} from 'sentry/components/overlay';
 import type {TooltipProps} from 'sentry/components/tooltip';
 import {Tooltip} from 'sentry/components/tooltip';
 import {space} from 'sentry/styles/space';
 import domId from 'sentry/utils/domId';
+import mergeRefs from 'sentry/utils/mergeRefs';
 import type {FormSize} from 'sentry/utils/theme';
 
 /**
@@ -56,6 +60,10 @@ export type MenuListItemProps = {
    * Accented text and background (on hover) colors.
    */
   priority?: Priority;
+  /**
+   * Whether to show the details in an overlay when the item is hovered / focused.
+   */
+  showDetailsInOverlay?: boolean;
   /**
    * Determines the item's font sizes and internal paddings.
    */
@@ -115,11 +123,13 @@ function BaseMenuListItem({
   innerWrapProps = {},
   labelProps = {},
   detailsProps = {},
+  showDetailsInOverlay = false,
   tooltip,
   tooltipOptions = {delay: 500},
   forwardRef,
   ...props
 }: Props) {
+  const itemRef = useRef<HTMLLIElement>(null);
   const labelId = useMemo(() => domId('menuitem-label-'), []);
   const detailId = useMemo(() => domId('menuitem-details-'), []);
 
@@ -130,7 +140,7 @@ function BaseMenuListItem({
       aria-labelledby={labelId}
       aria-describedby={detailId}
       as={as}
-      ref={forwardRef}
+      ref={mergeRefs([forwardRef, itemRef])}
       {...props}
     >
       <Tooltip skipWrapper title={tooltip} {...tooltipOptions}>
@@ -167,7 +177,7 @@ function BaseMenuListItem({
               >
                 {label}
               </Label>
-              {details && (
+              {!showDetailsInOverlay && details && (
                 <Details
                   id={detailId}
                   disabled={disabled}
@@ -177,6 +187,11 @@ function BaseMenuListItem({
                   {details}
                 </Details>
               )}
+              {showDetailsInOverlay && details && isFocused && (
+                <DetailsOverlay size={size} id={detailId} itemRef={itemRef}>
+                  {details}
+                </DetailsOverlay>
+              )}
             </LabelWrap>
             {trailingItems && (
               <TrailingItems
@@ -203,6 +218,62 @@ const MenuListItem = memo(
 
 export default MenuListItem;
 
+function DetailsOverlay({
+  children,
+  size,
+  id,
+  itemRef,
+}: {
+  children: React.ReactNode;
+  id: string;
+  itemRef: React.RefObject<HTMLLIElement>;
+  size: Props['size'];
+}) {
+  const theme = useTheme();
+  const [overlayElement, setOverlayElement] = useState<HTMLDivElement | null>(null);
+  const popper = usePopper(itemRef.current, overlayElement, {
+    placement: 'right-start',
+    modifiers: [
+      {
+        name: 'offset',
+        options: {
+          offset: [0, 8],
+        },
+      },
+    ],
+  });
+
+  return createPortal(
+    <StyledPositionWrapper
+      {...popper.attributes.popper}
+      ref={setOverlayElement}
+      zIndex={theme.zIndex.tooltip}
+      style={popper.styles.popper}
+    >
+      <StyledOverlay id={id} placement="right-start" size={size}>
+        {children}
+      </StyledOverlay>
+    </StyledPositionWrapper>,
+    document.body
+  );
+}
+
+const StyledPositionWrapper = styled(PositionWrapper)`
+  &[data-popper-reference-hidden='true'] {
+    opacity: 0;
+    pointer-events: none;
+  }
+`;
+
+const StyledOverlay = styled(Overlay)<{
+  size: Props['size'];
+}>`
+  padding: ${p => getVerticalPadding(p.size)};
+  font-size: ${p => p.theme.form[p.size ?? 'md'].fontSize};
+  cursor: auto;
+  user-select: text;
+`;
+
 const MenuItemWrap = styled('li')`
   position: static;
   list-style-type: none;