Tooltip

[babycroc]

Summary

• Implement Tooltip component using v2 design tokens

Goals & Requirements

• Implement default variant of the Tooltip component
  • Support conditional rendering with showTitle and showHelpText props
  • Rename description prop to helpText for clarity
• Maintain all existing functionality and props
• shortCut variant of the Tooltip component needs more discussion

Design Details

export type TooltipVariant = 'default' | 'shortcut'

interface BaseTooltipProps {
  // Common props
  children: ReactNode
  content: ReactNode
  disabled?: boolean
  icon?: IconSource
  placement?: TooltipPosition
  offset?: number
  container?: HTMLElement
  keepInContainer?: boolean
  allowHover?: boolean
  delayShow?: number
  delayHide?: number
  defaultShow?: boolean
  onShow?: () => void
  onHide?: () => void
}

interface DefaultTooltipProps extends BaseTooltipProps {
  variant?: TooltipVariant.default
  showTitle?: boolean
  showHelpText?: boolean
  title?: ReactNode
  helpText?: ReactNode
}

interface ShortcutTooltipProps extends BaseTooltipProps {
  variant: TooltipVariant.shortcut
  // shortcut variant specific props can be added here
}

export type TooltipProps = DefaultTooltipProps | ShortcutTooltipProps

Use Cases

// 0. Most basic tooltip
<Tooltip content="Tooltip">
  <Button>Hover me</Button>
</Tooltip>

// 1. Basic text tooltip with emoji and help text
<Tooltip
  content={
    <HStack spacing={4}>
      <Text>🏝️ 반차중 이라고요허허</Text>
    </HStack>
  }
  showHelpText
  helpText="07-17 11:59 PM까지"
>
  <StatusBadge>반차중</StatusBadge>
</Tooltip>

// 2. Complex tooltip with title and help text
<Tooltip 
  content={
    <VStack spacing={4}>
      <Text>[Add] 배송조회 버튼 추가함</Text>
      <Text>[Delete] 시작단계에 있던 '상담원 연결하기' 버튼 삭제</Text>
      <Text>[Modify] 시작단계 메시지 포맷하게 수정</Text>
    </VStack>
  }
  showTitle
  title="배송 버튼 추가 /수정"
  showHelpText
  helpText="07-17 11:59 PM"
>
  <Button>History</Button>
</Tooltip>

// 3. Shortcut tooltip
// shortcut variant use case can be added here

Migration Considerations

• description → helpText
• All other props maintain their existing behavior

// Before
<Tooltip
  content="주요 내용"
  description="07-17 11:59 PM까지"
>
  <Button>Example</Button>
</Tooltip>

// After (v2)
<Tooltip
  content="주요 내용"             // maintain content prop
  showHelpText
  helpText="07-17 11:59 PM까지"  // description → helpText
>
  <Button>Example</Button>
</Tooltip>

Accessibility

Radix UI Base Accessibility

• Automatic role="tooltip" application
• ARIA attributes (aria-describedby, aria-labelledby) management
• Keyboard accessibility (Escape to close)
• Focus management

Test Plan

1. Core Functionality

describe('Tooltip', () => {
  it('renders and manages visibility correctly')
  it('handles variants (default/shortcut) properly')
  it('supports all positioning options')
  it('maintains backward compatibility')
})

2. Visual Testing

• Variant styles
• Dark/light themes
• Responsive behavior

Alternatives

1. Radix UI Based Implementation (Selected)

// @TooltipPrimitive.tsx + @Tooltip.tsx approach
<AlphaTooltipPrimitive>
  <AlphaTooltipPrimitiveTrigger>{children}</AlphaTooltipPrimitiveTrigger>
  <AlphaTooltipPrimitiveContent>{content}</AlphaTooltipPrimitiveContent>
</AlphaTooltipPrimitive>

• Advantages:
  • Proven accessibility
  • Reliable positioning
  • Consistency with existing codebase
• Adoption reasons:
  • Productivity and quality assurance
  • Maintainability
  • Suitable for v2 features

2. Pure DOM Implementation

// @LegacyTooltip.tsx approach
<div
  className={styles.LegacyTooltip}
  onMouseEnter={handleMouseEnter}
  onMouseLeave={handleMouseLeave}
>
  {children}
  {show && TooltipComponent}
</div>

• Advantages:
  • Full customization
  • Minimal dependencies
• Rejection reasons:
  • Accessibility implementation burden
  • Complex features need manual implementation
  • Higher maintenance cost

References

1. Accessibility Guidelines

• WAI-ARIA Tooltip Pattern
• MDN Tooltip Role
• Radix UI Tooltip Accessibility

2. Design System References

• Channel Design System - Tooltip
• Radix UI Tooltip
• Material UI Tooltip

3. Internal References

• @Tooltip.tsx
• @TooltipPrimitive.tsx
• @LegacyTooltip.tsx

[channeltalk]

https://desk.channel.io/#/channels/1/team_chats/groups/1237/67628d4fbe7dc2a60436

[sungik-choi]

1. 문서의 나머지 항목도 채워주실 수 있을까요? 아래와 같은 레퍼런스 참고해보셔도 좋을 거 같아요

• https://www.radix-ui.com/primitives/docs/components/tooltip#tooltip
• https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/

2. Design Details엔 디자인 시스템 컴포넌트에 대한 링크를 달아놓기보다, 코드로 구현했을 때 어떤 인터페이스를 가져야할지에 대해 작성해주시면 좋을 거 같아요
3. Use cases에 대해선 content prop에 대한 기본적인 예제 외에도, 기존 인터페이스의 어떤 부분을 유지시킬지, 새로운 컴포넌트 스펙과 충돌하는 부분은 어떻게 마이그레이션할 지 등 자세한 실제 사용처 에제들을 보여주시면 좋을 거 같아요. 예컨대 툴팁의 content 속성은 그대로 유지해야할지? 아니면 컴포넌트 스펙과 맞게 text 속성으로 이름을 변경해야할지? 같은 고민이 있을 거 같습니다.