@channel.io/bezier-react 1.6.1 → 1.7.0

package/src/components/Tooltip/Tooltip.test.tsx

@@ -1,99 +1,172 @@
 import React from 'react'
 
-import { fireEvent } from '@testing-library/dom'
-import { act } from '@testing-library/react'
-
-import { css } from '~/src/foundation'
+import {
+  isInaccessible,
+  waitFor,
+} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
 
 import { render } from '~/src/utils/testUtils'
 
-import Tooltip, {
-  TOOLTIP_CONTENT_TEST_ID,
-  TOOLTIP_TEST_ID,
+import {
+  Tooltip,
+  TooltipProvider,
 } from './Tooltip'
-import type TooltipProps from './Tooltip.types'
-
-const RootTooltip: React.FC<TooltipProps> = ({ children, ...rests }) => (
-  <Tooltip {...rests}>
-    { children }
-  </Tooltip>
-)
-
-describe('Tooltip test >', () => {
-  let props: TooltipProps
+import {
+  type TooltipProps,
+  type TooltipProviderProps,
+} from './Tooltip.types'
+
+describe('Tooltip', () => {
+  const renderTooltip = ({
+    children,
+    ...rest
+  }: TooltipProps = {}) => render(
+    <Tooltip {...rest}>
+      <button type="button">
+        Trigger
+      </button>
+    </Tooltip>,
+  )
 
-  const content = 'Hovered'
+  let user: ReturnType<typeof userEvent.setup>
 
   beforeEach(() => {
-    props = {
-      children: 'Text',
-      content,
-    }
-
-    jest.useFakeTimers()
+    user = userEvent.setup()
   })
 
-  afterEach(() => {
-    jest.useRealTimers()
-  })
+  describe('ARIA', () => {
+    it('should be accessible', () => {
+      const { container } = renderTooltip({ defaultShow: true })
+      expect(isInaccessible(container)).toBe(false)
+    })
 
-  const renderTooltip = (optionProps?: TooltipProps) => render(
-    <RootTooltip {...props} {...optionProps} />,
-  )
+    it('The element that serves as the tooltip container has role `tooltip`.', () => {
+      const { getByRole } = renderTooltip({ defaultShow: true })
+      expect(getByRole('tooltip')).toBeInTheDocument()
+    })
 
-  it('Tooltip with default props', () => {
-    const { baseElement, getByTestId } = renderTooltip()
+    it('The element that triggers the tooltip references the tooltip element with `aria-describedby`.', () => {
+      const { getByRole } = renderTooltip({ defaultShow: true })
+      expect(getByRole('button')).toHaveAttribute('aria-describedby', getByRole('tooltip').id)
+    })
+  })
 
-    act(() => {
-      fireEvent.mouseOver(getByTestId(TOOLTIP_TEST_ID))
+  describe('User Interactions', () => {
+    it('The tooltip content should be visible when hover over the trigger.', async () => {
+      const { getByRole } = renderTooltip()
+      await user.hover(getByRole('button'))
+      expect(getByRole('tooltip')).toBeInTheDocument()
+    })
 
-      jest.runAllTimers()
+    it('The tooltip content should be visible when the keyboard focuses on the trigger.', async () => {
+      const { getByRole } = renderTooltip()
+      await user.tab()
+      expect(getByRole('tooltip')).toBeInTheDocument()
     })
 
-    expect(baseElement).toMatchSnapshot()
-  })
+    it('When the tooltip content is visible, pressing Esc should hide the tooltip content.', async () => {
+      const { queryByRole } = renderTooltip({ defaultShow: true })
+      await user.keyboard('{Escape}')
+      expect(queryByRole('tooltip')).not.toBeInTheDocument()
+    })
 
-  it('Tooltip with contentInterpolation prop', async () => {
-    const { baseElement, getByTestId } = renderTooltip({
-      contentInterpolation: css`background-color: black;`,
+    it('When the `allowHover` property is true, the tooltip content should be hoverable.', async () => {
+      const { getByRole } = renderTooltip({ allowHover: true })
+      await user.hover(getByRole('button'))
+      await user.hover(getByRole('tooltip'))
+      expect(getByRole('tooltip')).toBeInTheDocument()
     })
 
-    act(() => {
-      fireEvent.mouseOver(getByTestId(TOOLTIP_TEST_ID))
+    it('When the tooltip is visible, the `onShow` handler should be called.', async () => {
+      const onShow = jest.fn()
+      const { getByRole } = renderTooltip({ onShow })
+      await user.hover(getByRole('button'))
+      expect(onShow).toHaveBeenCalled()
+    })
 
-      jest.runAllTimers()
+    it('When the tooltip is hidden, the `onHide` handler should be called.', async () => {
+      const onHide = jest.fn()
+      const { getByRole } = renderTooltip({ onHide })
+      await user.hover(getByRole('button'))
+      await user.unhover(getByRole('button'))
+      expect(onHide).toHaveBeenCalled()
     })
 
-    expect(baseElement).toMatchSnapshot()
-  })
+    it('If the `disabled` property is true, the tooltip should not be visible when hovering over it or with keyboard focus.', async () => {
+      const { getByRole, queryByRole } = renderTooltip({ disabled: true })
+      await user.hover(getByRole('button'))
+      expect(queryByRole('tooltip')).not.toBeInTheDocument()
+      await user.tab()
+      expect(queryByRole('tooltip')).not.toBeInTheDocument()
+    })
 
-  it('TooltipContent not rendered at first', async () => {
-    const { queryByTestId } = renderTooltip()
+    it('If the `delayShow` property is greater than 0, the tooltip should be delayed by that number of ms before appearing.', async () => {
+      const { getByRole, queryByRole } = renderTooltip({ delayShow: 1000 })
+      await user.hover(getByRole('button'))
+      expect(queryByRole('tooltip')).not.toBeInTheDocument()
+      await waitFor(() => {
+        expect(queryByRole('tooltip')).toBeInTheDocument()
+      }, { timeout: 1000 })
+    })
 
-    expect(queryByTestId(TOOLTIP_CONTENT_TEST_ID)).toBeNull()
+    it('If the `delayHide` property is greater than 0, the tooltip should be delayed by that number of ms before disappearing.', async () => {
+      const { getByRole, queryByRole } = renderTooltip({ delayHide: 1000 })
+      await user.hover(getByRole('button'))
+      await user.unhover(getByRole('button'))
+      expect(queryByRole('tooltip')).toBeInTheDocument()
+      await waitFor(() => {
+        expect(queryByRole('tooltip')).not.toBeInTheDocument()
+      }, { timeout: 1000 })
+    })
   })
+})
 
-  it('TooltipContent rendered after mouseover', async () => {
-    const { getByTestId, queryByTestId } = renderTooltip()
-
-    act(() => {
-      fireEvent.mouseOver(getByTestId(TOOLTIP_TEST_ID))
+describe('TooltipProvider', () => {
+  const renderTooltipProvider = ({
+    children,
+    ...rest
+  }: TooltipProviderProps = {}) => render(
+    <TooltipProvider {...rest}>
+      <Tooltip>
+        <button type="button">
+          Trigger
+        </button>
+      </Tooltip>
+    </TooltipProvider>,
+  )
 
-      jest.runAllTimers()
-    })
+  let user: ReturnType<typeof userEvent.setup>
 
-    expect(queryByTestId(TOOLTIP_CONTENT_TEST_ID)).toBeVisible()
+  beforeEach(() => {
+    user = userEvent.setup()
   })
 
-  it('Tooltip with disabled prop not rendered even after mouseover', async () => {
-    const { getByTestId, queryByTestId } = renderTooltip({ disabled: true })
-
-    act(() => {
-      fireEvent.mouseOver(getByTestId(TOOLTIP_TEST_ID))
+  describe('User Interactions', () => {
+    it('If the `allowHover` property is true, the tooltip content should be hoverable.', async () => {
+      const { getByRole } = renderTooltipProvider({ allowHover: true })
+      await user.hover(getByRole('button'))
+      await user.hover(getByRole('tooltip'))
+      expect(getByRole('tooltip')).toBeInTheDocument()
+    })
 
-      jest.runAllTimers()
+    it('If the `delayShow` property is greater than 0, the tooltip should be delayed by that number of ms before appearing.', async () => {
+      const { getByRole, queryByRole } = renderTooltipProvider({ delayShow: 1000 })
+      await user.hover(getByRole('button'))
+      expect(queryByRole('tooltip')).not.toBeInTheDocument()
+      await waitFor(() => {
+        expect(queryByRole('tooltip')).toBeInTheDocument()
+      }, { timeout: 1000 })
     })
 
-    expect(queryByTestId(TOOLTIP_CONTENT_TEST_ID)).toBeNull()
+    it('If the `delayHide` property is greater than 0, the tooltip should be delayed by that number of ms before disappearing.', async () => {
+      const { getByRole, queryByRole } = renderTooltipProvider({ delayHide: 1000 })
+      await user.hover(getByRole('button'))
+      await user.unhover(getByRole('button'))
+      expect(queryByRole('tooltip')).toBeInTheDocument()
+      await waitFor(() => {
+        expect(queryByRole('tooltip')).not.toBeInTheDocument()
+      }, { timeout: 1000 })
+    })
   })
 })

package/src/components/Tooltip/Tooltip.tsx

@@ -1,5 +1,4 @@
 import React, {
-  type Ref,
   forwardRef,
   useCallback,
   useEffect,
@@ -8,146 +7,289 @@ import React, {
   useState,
 } from 'react'
 
-import { window } from '~/src/utils/domUtils'
-
-import type TooltipProps from './Tooltip.types'
-import { TooltipPosition } from './Tooltip.types'
-import TooltipContent from './TooltipContent'
-
-import { Container } from './Tooltip.styled'
-
-export const TOOLTIP_TEST_ID = 'bezier-react-tooltip'
-export const TOOLTIP_CONTENT_TEST_ID = 'bezier-react-tooltip-content'
-
-function Tooltip(
-  {
-    as,
-    testId = TOOLTIP_TEST_ID,
-    contentTestId = TOOLTIP_CONTENT_TEST_ID,
-    className,
-    contentClassName,
-    contentInterpolation,
-    contentWrapperStyle,
-    content = null,
-    lazy = false, // optional prop 에서 추후 default behavior 를 lazy 하게 바꿀 예정
-    placement = TooltipPosition.BottomCenter,
-    disabled = false,
-    offset = 4,
-    keepInContainer = false,
-    allowHover = false,
-    delayShow = 0,
-    delayHide = 0,
-    children,
-    ...otherProps
-  }: TooltipProps,
-  forwardedRef: Ref<any>,
+import * as TooltipPrimitive from '@radix-ui/react-tooltip'
+
+import { document } from '~/src/utils/domUtils'
+import { isBoolean } from '~/src/utils/typeUtils'
+
+import {
+  TooltipPosition,
+  type TooltipProps,
+  type TooltipProviderProps,
+} from './Tooltip.types'
+
+import * as Styled from './Tooltip.styled'
+
+// TODO: (@ed) Evolve it into a commonly reusable function
+// FIXME: duplicate
+function createContext<ContextValue>(
+  providerName: string,
+  defaultValue: ContextValue,
 ) {
-  const [show, setShow] = useState(false)
-  const [didMount, setDidMount] = useState(show)
+  const Context = React.createContext<ContextValue>(defaultValue)
 
-  const tooltipContainerRef = useRef<HTMLDivElement>(null)
-  const timerRef = useRef<ReturnType<Window['setTimeout']>>()
+  function useContext(consumerName: string) {
+    const contextValue = React.useContext(Context)
 
-  useEffect(function hideTooltipContentWhenDisabled() {
-    if (disabled) {
-      setShow(false)
+    if (!contextValue) {
+      throw new Error(`'${consumerName}' must be used within '${providerName}'`)
     }
-  }, [disabled])
 
-  useEffect(function updateDidMount() {
-    setDidMount((prev) => prev || show)
-  }, [show])
+    return contextValue
+  }
+
+  return [
+    Context.Provider,
+    useContext,
+  ] as const
+}
 
-  const handleMouseEnter = useCallback(() => {
-    if (disabled) {
-      return
-    }
+function getSideAndAlign(
+  placement: TooltipPosition,
+): Pick<TooltipPrimitive.TooltipContentProps, 'side' | 'align'> {
+  switch (placement) {
+    case TooltipPosition.TopCenter:
+      return {
+        side: 'top',
+        align: 'center',
+      }
+    case TooltipPosition.TopLeft:
+      return {
+        side: 'top',
+        align: 'start',
+      }
+    case TooltipPosition.TopRight:
+      return {
+        side: 'top',
+        align: 'end',
+      }
+    case TooltipPosition.RightCenter:
+      return {
+        side: 'right',
+        align: 'center',
+      }
+    case TooltipPosition.RightTop:
+      return {
+        side: 'right',
+        align: 'start',
+      }
+    case TooltipPosition.RightBottom:
+      return {
+        side: 'right',
+        align: 'end',
+      }
+    case TooltipPosition.BottomCenter:
+      return {
+        side: 'bottom',
+        align: 'center',
+      }
+    case TooltipPosition.BottomLeft:
+      return {
+        side: 'bottom',
+        align: 'start',
+      }
+    case TooltipPosition.BottomRight:
+      return {
+        side: 'bottom',
+        align: 'end',
+      }
+    case TooltipPosition.LeftCenter:
+      return {
+        side: 'left',
+        align: 'center',
+      }
+    case TooltipPosition.LeftTop:
+      return {
+        side: 'left',
+        align: 'start',
+      }
+    case TooltipPosition.LeftBottom:
+      return {
+        side: 'left',
+        align: 'end',
+      }
+    default:
+      // NOTE: should not reach here
+      return {
+        side: undefined,
+        align: undefined,
+      }
+  }
+}
+
+const [
+  /**
+   * NOTE: Custom context use because the radix-ui doesn't support `delayHide`.
+   */
+  TooltipGlobalContextProvider,
+  useTooltipGlobalContext,
+] = createContext<Required<Pick<TooltipProviderProps, 'delayHide'>> | null>('TooltipProvider', null)
+
+/**
+ * `TooltipProvider` is used to globally provide props to child tooltips.
+ *
+ * @example
+ *
+ * ```tsx
+ * <TooltipProvider allowHover delayShow={1000}>
+ *   <Tooltip />
+ * </TooltipProvider>
+ * ```
+ */
+export function TooltipProvider({
+  children,
+  allowHover = false,
+  delayShow = 0,
+  delayHide = 0,
+  skipDelayShow = 0,
+}: TooltipProviderProps) {
+  const contextValue = useMemo(() => ({
+    delayHide,
+  }), [delayHide])
+
+  return (
+    <TooltipPrimitive.Provider
+      delayDuration={delayShow}
+      skipDelayDuration={skipDelayShow}
+      disableHoverableContent={!allowHover}
+    >
+      <TooltipGlobalContextProvider value={contextValue}>
+        { children }
+      </TooltipGlobalContextProvider>
+    </TooltipPrimitive.Provider>
+  )
+}
+
+/**
+ * `Tooltip` is a component that shows additional information when the mouse hovers or the keyboard is focused.
+ *
+ * @example
+ *
+ * ```tsx
+ * // Anatomy of the Tooltip
+ * <TooltipProvider>
+ *   <Tooltip />
+ * </TooltipProvider>
+ *
+ * // Example of a Tooltip with a button
+ * <Tooltip content="Ta-da!">
+ *   <button>Hover me</button>
+ * </Tooltip>
+ * ```
+ */
+export const Tooltip = forwardRef<HTMLDivElement, TooltipProps>(function Tooltip({
+  as,
+  children,
+  defaultShow,
+  onShow: onShowProp,
+  onHide: onHideProp,
+  disabled,
+  content,
+  description,
+  icon,
+  placement = TooltipPosition.BottomCenter,
+  offset = 4,
+  container = document.body,
+  keepInContainer = true,
+  allowHover,
+  delayShow,
+  delayHide: delayHideProp,
+  ...rest
+}, forwardedRef) {
+  const [show, setShow] = useState<boolean>(defaultShow ?? false)
+  const timeoutRef = useRef<NodeJS.Timeout>()
+  const { delayHide: globalDelayHide } = useTooltipGlobalContext('Tooltip')
 
-    if (timerRef.current) {
-      clearTimeout(timerRef.current)
+  const delayHide = delayHideProp ?? globalDelayHide
+
+  useEffect(function cleanUpTimeout() {
+    return function cleanUp() {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
     }
+  }, [])
 
-    timerRef.current = window.setTimeout(() => {
-      setShow(true)
-    }, delayShow)
-  }, [
-    delayShow,
-    disabled,
-  ])
+  const onShow = useCallback(() => {
+    setShow(true)
+    onShowProp?.()
+  }, [onShowProp])
+
+  const onHide = useCallback(() => {
+    setShow(false)
+    onHideProp?.()
+  }, [onHideProp])
 
-  const handleMouseLeave = useCallback(() => {
-    if (disabled) {
+  const onOpenChange = useCallback((open: boolean) => {
+    if (disabled) { return }
+
+    if (open) {
+      onShow()
       return
     }
 
-    if (timerRef.current) {
-      clearTimeout(timerRef.current)
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = undefined
     }
 
-    timerRef.current = window.setTimeout(() => {
-      setShow(false)
-    }, delayHide)
-  }, [
-    delayHide,
-    disabled,
-  ])
-
-  const TooltipComponent = useMemo(() => {
-    if (!lazy || didMount) {
-      return (
-        <TooltipContent
-          as={as}
-          content={content}
-          contentClassName={contentClassName}
-          contentInterpolation={contentInterpolation}
-          contentWrapperStyle={contentWrapperStyle}
-          disabled={disabled}
-          placement={placement}
-          offset={offset}
-          allowHover={allowHover}
-          keepInContainer={keepInContainer}
-          tooltipContainer={tooltipContainerRef.current}
-          forwardedRef={forwardedRef}
-          testId={contentTestId}
-        />
-      )
+    if (delayHide > 0) {
+      timeoutRef.current = setTimeout(() => {
+        onHide()
+      }, delayHide)
+      return
     }
 
-    return null
+    onHide()
   }, [
-    lazy,
-    didMount,
-    as,
-    content,
-    contentClassName,
-    contentInterpolation,
-    contentWrapperStyle,
     disabled,
-    placement,
-    offset,
-    allowHover,
-    keepInContainer,
-    forwardedRef,
-    contentTestId,
+    delayHide,
+    onShow,
+    onHide,
   ])
 
-  if (!children) {
-    return null
-  }
-
   return (
-    <Container
-      ref={tooltipContainerRef}
-      data-testid={testId}
-      className={className}
-      onMouseEnter={handleMouseEnter}
-      onMouseLeave={handleMouseLeave}
-      {...otherProps}
+    <TooltipPrimitive.Root
+      open={show}
+      defaultOpen={defaultShow}
+      delayDuration={delayShow}
+      disableHoverableContent={isBoolean(allowHover) ? !allowHover : undefined}
+      onOpenChange={onOpenChange}
     >
-      { children }
-      { show && TooltipComponent }
-    </Container>
-  )
-}
+      <TooltipPrimitive.Trigger asChild>
+        { children }
+      </TooltipPrimitive.Trigger>
+
+      <TooltipPrimitive.Portal container={container}>
+        <TooltipPrimitive.Content
+          {...rest}
+          {...getSideAndAlign(placement)}
+          asChild
+          ref={forwardedRef}
+          sideOffset={offset}
+          avoidCollisions={keepInContainer}
+          collisionPadding={8}
+          hideWhenDetached
+        >
+          <Styled.TooltipContent forwardedAs={as}>
+            <Styled.TextContainer>
+              <Styled.Content>
+                { content }
+              </Styled.Content>
 
-export default React.memo(forwardRef(Tooltip))
+              { description && (
+                <Styled.Description>
+                  { description }
+                </Styled.Description>
+              ) }
+            </Styled.TextContainer>
+
+            { icon && (
+              <Styled.Icon source={icon} />
+            ) }
+          </Styled.TooltipContent>
+        </TooltipPrimitive.Content>
+      </TooltipPrimitive.Portal>
+    </TooltipPrimitive.Root>
+  )
+})