# Tooltip

## Introduction

Tooltip 컴포넌트는 사용자가 요소에 마우스를 올렸을 때 추가적인 정보나 도움말을 제공하는 오버레이입니다. Joy UI의 Tooltip을 기반으로 하며, 사용자 경험을 향상시키기 위해 간결하고 유용한 정보를 표시하는 데 사용됩니다. 버튼 설명, 아이콘 의미, 잘린 텍스트의 전체 내용 표시 등에 활용됩니다.

```tsx
<Tooltip
  title="I am Tooltip"
  arrow={false}
  children={<Button>Hover me</Button>}
/>
```

| Field    | Description | Default                     |
| -------- | ----------- | --------------------------- |
| variant  | —           | —                           |
| color    | —           | —                           |
| size     | —           | —                           |
| arrow    | —           | false                       |
| open     | —           | —                           |
| children | —           | \<Button>Hover me\</Button> |

## Usage

```tsx
import { Tooltip, Button } from '@ceed/ads';

function MyComponent() {
  return (
    <Tooltip title="이 버튼을 클릭하면 저장됩니다">
      <Button>저장</Button>
    </Tooltip>
  );
}
```

## Examples

### Basic Usage

가장 기본적인 Tooltip 사용법입니다.

```tsx
<Tooltip
  title="I am Tooltip"
  arrow={false}
  children={<Button>Hover me</Button>}
/>
```

### Controlled Tooltip

프로그래밍적으로 제어되는 Tooltip입니다.

```tsx
<Tooltip
  title="I am Tooltip"
  arrow={false}
  children={<Button>Hover me</Button>}
  open
/>
```

## Common Use Cases

### Icon Button Descriptions

아이콘 버튼의 의미를 설명할 때 사용합니다.

```tsx
<Stack direction="row" spacing={1}>
  <Tooltip title="편집">
    <IconButton size="sm">
      <EditIcon />
    </IconButton>
  </Tooltip>

  <Tooltip title="삭제">
    <IconButton size="sm" color="danger">
      <DeleteIcon />
    </IconButton>
  </Tooltip>

  <Tooltip title="공유">
    <IconButton size="sm">
      <ShareIcon />
    </IconButton>
  </Tooltip>
</Stack>
```

### Truncated Text

잘린 텍스트의 전체 내용을 표시할 때 사용합니다.

```tsx
function TruncatedText({ text }: { text: string }) {
  const shouldTruncate = text.length > 50;
  const displayText = shouldTruncate ? `${text.substring(0, 50)}...` : text;

  const content = (
    <Typography
      level="body-md"
      sx={{
        maxWidth: 300,
        overflow: 'hidden',
        textOverflow: 'ellipsis',
        whiteSpace: 'nowrap',
      }}
    >
      {displayText}
    </Typography>
  );

  return shouldTruncate ? <Tooltip title={text}>{content}</Tooltip> : content;
}
```

### Form Field Help

폼 필드에 추가 도움말을 제공할 때 사용합니다.

```tsx
<Stack spacing={2}>
  <FormControl>
    <FormLabel>
      비밀번호
      <Tooltip title="최소 8자 이상, 대소문자와 숫자를 포함해야 합니다">
        <IconButton size="sm" variant="plain" color="neutral">
          <InfoIcon />
        </IconButton>
      </Tooltip>
    </FormLabel>
    <Input type="password" />
  </FormControl>
</Stack>
```

### Status Indicators

상태나 진행률 정보를 표시할 때 사용합니다.

```tsx
<Stack direction="row" spacing={2} alignItems="center">
  <Tooltip title="성공적으로 완료됨">
    <Chip color="success" variant="soft">
      <CheckCircleIcon sx={{ mr: 1 }} />
      완료
    </Chip>
  </Tooltip>

  <Tooltip title="진행 중... 예상 완료 시간: 5분">
    <Chip color="warning" variant="soft">
      <AccessTimeIcon sx={{ mr: 1 }} />
      진행중
    </Chip>
  </Tooltip>

  <Tooltip title="오류가 발생했습니다. 다시 시도해주세요">
    <Chip color="danger" variant="soft">
      <ErrorIcon sx={{ mr: 1 }} />
      실패
    </Chip>
  </Tooltip>
</Stack>
```

### Navigation Hints

네비게이션 요소에 도움말을 제공할 때 사용합니다.

```tsx
<Stack direction="row" spacing={2}>
  <Tooltip title="홈페이지로 이동">
    <Button variant="plain" startDecorator={<HomeIcon />}>
      홈
    </Button>
  </Tooltip>

  <Tooltip title="사용자 프로필 및 설정">
    <Button variant="plain" startDecorator={<PersonIcon />}>
      프로필
    </Button>
  </Tooltip>

  <Tooltip title="알림 및 메시지 확인">
    <Badge badgeContent={3} color="danger">
      <Button variant="plain" startDecorator={<NotificationsIcon />}>
        알림
      </Button>
    </Badge>
  </Tooltip>
</Stack>
```

### Complex Content

복잡한 내용을 가진 Tooltip입니다.

```tsx
<Tooltip
  title={
    <Stack spacing={1} sx={{ maxWidth: 250 }}>
      <Typography level="title-sm">사용자 정보</Typography>
      <Typography level="body-sm">
        이름: 김철수
        <br />
        부서: 개발팀
        <br />
        직급: 선임연구원
        <br />
        연락처: kim@example.com
      </Typography>
    </Stack>
  }
  variant="outlined"
>
  <Avatar>김</Avatar>
</Tooltip>
```

### Interactive Elements

상호작용이 가능한 요소들과 함께 사용합니다.

```tsx
<Stack direction="row" spacing={2}>
  <Tooltip title="이 기능은 프리미엄 사용자만 이용할 수 있습니다">
    <Button disabled>프리미엄 기능</Button>
  </Tooltip>

  <Tooltip title="현재 선택됨">
    <Chip variant="solid" color="primary">
      활성 필터
    </Chip>
  </Tooltip>

  <Tooltip title="클릭하여 정렬 순서 변경">
    <Button variant="plain" endDecorator={<ArrowDropDownIcon />}>
      이름순
    </Button>
  </Tooltip>
</Stack>
```

## Props and Customization

### Title Prop

Tooltip에 표시될 내용을 지정합니다.

```tsx
// 간단한 텍스트
<Tooltip title="간단한 도움말">
  <Button>버튼</Button>
</Tooltip>

// React 요소
<Tooltip
  title={
    <div>
      <strong>제목</strong><br />
      상세 설명이 들어갑니다.
    </div>
  }
>
  <Button>버튼</Button>
</Tooltip>
```

### Placement

Tooltip이 나타나는 위치를 조정할 수 있습니다.

```tsx
<Stack direction="row" spacing={2} sx={{ mt: 4 }}>
  <Tooltip title="위쪽" placement="top">
    <Button>Top</Button>
  </Tooltip>

  <Tooltip title="아래쪽" placement="bottom">
    <Button>Bottom</Button>
  </Tooltip>

  <Tooltip title="왼쪽" placement="left">
    <Button>Left</Button>
  </Tooltip>

  <Tooltip title="오른쪽" placement="right">
    <Button>Right</Button>
  </Tooltip>
</Stack>
```

### Colors and Variants

다양한 색상과 변형을 적용할 수 있습니다.

```tsx
<Stack direction="row" spacing={2}>
  <Tooltip title="Primary 색상" color="primary" variant="solid">
    <Button>Primary</Button>
  </Tooltip>

  <Tooltip title="Success 색상" color="success" variant="soft">
    <Button>Success</Button>
  </Tooltip>

  <Tooltip title="Warning 색상" color="warning" variant="outlined">
    <Button>Warning</Button>
  </Tooltip>

  <Tooltip title="Danger 색상" color="danger" variant="plain">
    <Button>Danger</Button>
  </Tooltip>
</Stack>
```

### Arrow

화살표를 표시하여 Tooltip이 어느 요소를 가리키는지 명확히 할 수 있습니다.

```tsx
<Stack direction="row" spacing={2}>
  <Tooltip title="화살표 없음" arrow={false}>
    <Button>No Arrow</Button>
  </Tooltip>

  <Tooltip title="화살표 있음" arrow={true}>
    <Button>With Arrow</Button>
  </Tooltip>
</Stack>
```

### Controlled Mode

프로그래밍적으로 Tooltip의 표시/숨김을 제어할 수 있습니다.

```tsx
function ControlledTooltip() {
  const [open, setOpen] = useState(false);

  return (
    <Stack spacing={2}>
      <Tooltip title="이 Tooltip은 버튼으로 제어됩니다" open={open} onClose={() => setOpen(false)}>
        <Button variant="outlined">제어되는 요소</Button>
      </Tooltip>

      <Button onClick={() => setOpen(!open)}>Tooltip {open ? '숨기기' : '보이기'}</Button>
    </Stack>
  );
}
```

## Accessibility

Tooltip 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:

### ARIA 속성

자동으로 적절한 ARIA 속성이 적용됩니다.

```tsx
<Tooltip title="저장 버튼">
  <Button aria-label="문서 저장">
    <SaveIcon />
  </Button>
</Tooltip>
```

### 키보드 지원

키보드 사용자도 Tooltip을 사용할 수 있습니다.

- **Tab**: 포커스 가능한 요소로 이동
- **Escape**: 열린 Tooltip 닫기

### 터치 기기 지원

터치 기기에서도 Tooltip을 사용할 수 있도록 탭 제스처를 지원합니다.

```tsx
<Tooltip title="터치 기기에서도 동작합니다" touchTapDelay={0}>
  <Button>터치 지원</Button>
</Tooltip>
```

## Best Practices

1. **간결한 내용**: Tooltip 내용은 간결하고 이해하기 쉽게 작성하세요.

```tsx
// ✅ 좋은 예
<Tooltip title="삭제">
  <IconButton><DeleteIcon /></IconButton>
</Tooltip>

// ❌ 나쁜 예
<Tooltip title="이 버튼을 클릭하면 선택된 항목이 영구적으로 삭제되며 복구할 수 없습니다">
  <IconButton><DeleteIcon /></IconButton>
</Tooltip>
```

2. **중요한 정보는 다른 방법으로**: 핵심적인 정보는 Tooltip에만 의존하지 마세요.

3. **적절한 타이밍**: 사용자가 도움이 필요할 때만 표시되도록 하세요.

4. **일관된 배치**: 애플리케이션 전체에서 일관된 placement를 사용하세요.

5. **성능 고려**: 많은 수의 Tooltip이 있는 페이지에서는 필요시에만 렌더링하세요.

```tsx
// 조건부 Tooltip
{
  (needsTooltip && (
    <Tooltip title="도움말">
      <Button>버튼</Button>
    </Tooltip>
  )) || <Button>버튼</Button>;
}
```

6. **모바일 고려**: 모바일 환경에서는 대안적인 정보 제공 방법을 고려하세요.

7. **색상 의존 금지**: 색상에만 의존하지 말고 텍스트나 아이콘으로도 정보를 전달하세요.

## Performance Considerations

1. **지연 렌더링**: 많은 Tooltip이 있는 경우 필요시에만 렌더링하세요.

2. **메모이제이션**: 복잡한 title 내용은 메모이제이션을 고려하세요.

```tsx
const tooltipContent = useMemo(() => <ComplexTooltipContent data={data} />, [data]);

<Tooltip title={tooltipContent}>
  <Button>복잡한 Tooltip</Button>
</Tooltip>;
```

3. **이벤트 리스너 최적화**: 커스텀 이벤트 핸들러를 사용할 때는 적절히 정리하세요.

Tooltip은 사용자에게 추가적인 맥락과 도움을 제공하는 중요한 UI 컴포넌트입니다. 적절히 사용하면 사용자 경험을 크게 향상시킬 수 있습니다.
