114 lines
6.0 KiB
Markdown
114 lines
6.0 KiB
Markdown
# Tooltip
|
|
|
|
현재 HM 구현의 기준 문서. 공통 원칙은 `docs/guidelines/프로젝트-지침.md`(§6, §7), Token 구조 원칙은 `테마-토큰-가이드.md`를 따른다. 이 문서는 Tooltip 고유의 API·Token·상태·결정만 기록한다.
|
|
|
|
## 1. 상태
|
|
|
|
| 항목 | 내용 |
|
|
|---|---|
|
|
| 구현 상태 | 구현 완료 (현재 HM 규격) |
|
|
| 기준일 | 2026-10-02 |
|
|
| 기반 | shadcn/ui Tooltip (Radix `Tooltip`) |
|
|
| 대표 Story | `Components/Overlay/Tooltip` → `All` (이름 "Tooltip") |
|
|
| 보류 | 아래 §11 |
|
|
|
|
## 2. 적용 근거
|
|
|
|
- **참고 근거**: 외부 ui_viz Reference (ZIP 미포함)의 기존 테스트 규격에는 Tooltip 규격이 없다(인벤토리 "상세 동작·디자인 보류"). 참고할 수치가 없었다.
|
|
- **현재 HM 규격**: 아래 §3~§4. 현재 HM Semantic 체계(fg-primary, text-inverse)로 새로 정했다.
|
|
- **구현 방식**: shadcn / Radix Tooltip 구조(Provider, Root, Trigger, Content, Arrow)를 유지하고 theme CSS로 HM 스타일을 연결.
|
|
- **보류**: §11.
|
|
|
|
## 3. 기본 규격 (현재 HM 규격)
|
|
|
|
| 항목 | 값 |
|
|
|---|---|
|
|
| Background | `--hm-sem-fg-primary` (진한 녹색) |
|
|
| Text | `--hm-color-text-inverse` (White) |
|
|
| Radius | `--hm-radius-container` (4px) |
|
|
| Padding | 6px 10px |
|
|
| Max width | 240px, 긴 문장은 줄바꿈(`text-balance`, `overflow-wrap: anywhere`) |
|
|
| Typography | 12 / 18 / 400 |
|
|
| Arrow | shadcn 회전 사각형, 면과 같은 색(배경·fill) |
|
|
| Position | `sideOffset` 4, shadcn 기본 side(top) |
|
|
| Delay | `TooltipProvider delayDuration` 기본 0 (shadcn 기본 유지) |
|
|
|
|
Tooltip은 짧고 즉각적인 설명만 담는다. 긴 설명·interactive 콘텐츠는 Popover / Hover Card를 쓴다. 그림자와 border는 없다.
|
|
|
|
## 4. 상태 규격
|
|
|
|
| 상태 | 값 |
|
|
|---|---|
|
|
| Open / Closed | Radix `data-state`(`delayed-open` 포함), shadcn open/close animation |
|
|
| 열림 조건 | trigger hover 또는 keyboard focus |
|
|
| 닫힘 조건 | pointer leave, blur, Escape, trigger 클릭 |
|
|
|
|
## 5. API
|
|
|
|
Radix Tooltip props 그대로. export: `TooltipProvider`, `Tooltip`, `TooltipTrigger`, `TooltipContent`.
|
|
|
|
- `Tooltip`은 상위 HM `TooltipProvider`가 없을 때만 자체 Provider를 만든다. 단독 사용은 그대로 지원하며 기본 `delayDuration`은 0이다.
|
|
- 그룹에는 `@hm-design/ui`의 `TooltipProvider`를 둔다. 내부 Provider를 추가하지 않아 가장 가까운 Provider의 `delayDuration`, `skipDelayDuration`, `disableHoverableContent`와 그룹의 skip-delay 상태를 공유한다. Radix Provider를 직접 사용하는 대신 HM Provider를 사용한다.
|
|
- 개별 `Tooltip delayDuration`은 Provider의 delay를 override한다. `skipDelayDuration`은 Provider에서 지정하며, skip 구간의 다음 Tooltip은 즉시 열린다. `skipDelayDuration={0}`이면 각 hover에 delay가 적용된다. keyboard focus는 delay 없이 열리고 Escape로 닫힌다.
|
|
- `TooltipContent`: `sideOffset` 기본 4. 출력 속성: `data-slot="tooltip-*"`, Radix `data-state`·`data-side`. Arrow는 `data-slot="tooltip-arrow"`.
|
|
|
|
```tsx
|
|
<TooltipProvider delayDuration={700} skipDelayDuration={300}>
|
|
<Tooltip>
|
|
<TooltipTrigger asChild><button>저장</button></TooltipTrigger>
|
|
<TooltipContent>변경 사항을 저장합니다</TooltipContent>
|
|
</Tooltip>
|
|
{/* 같은 Provider 아래의 Tooltip은 skip-delay 상태를 공유한다. */}
|
|
</TooltipProvider>
|
|
```
|
|
|
|
## 6. Token
|
|
|
|
Component Mapping 위치: `packages/ui/src/theme/tooltip.css` (`--hm-tooltip-*`).
|
|
|
|
`background`, `text`, `radius`, `padding-x`, `padding-y`, `max-width`, `font-size`, `line-height`, `font-weight`. 다른 컴포넌트의 Component Token을 참조하지 않는다. 신규 Primitive 없음.
|
|
|
|
## 7. shadcn / Radix에서 유지한 항목
|
|
|
|
Radix 구조·ARIA(`role=tooltip`, `aria-describedby`)·Escape·hover/focus 동작, Provider 구조와 delay, Portal·positioning·collision, `data-slot`, `cn(..., className)`, animation class, `z-50`, Arrow.
|
|
|
|
## 8. HM에서 변경한 항목
|
|
|
|
- shadcn `bg-foreground text-background rounded-md px-3 py-1.5 text-xs` 및 arrow의 `bg-foreground fill-foreground` class 제거 → theme CSS.
|
|
- 최대 폭 240px 추가(shadcn은 `w-fit`만 있어 긴 문장 한계가 없었다).
|
|
|
|
## 9. Storybook
|
|
|
|
- 대표 Story `All`("Tooltip"): 기본, 긴 텍스트, 비활성 버튼(wrapper trigger), 4방향 placement 비교.
|
|
- verification: `Open`(열린 상태).
|
|
- interactive control은 넣지 않는다.
|
|
|
|
## 10. 사용자 확정 결정
|
|
|
|
- 2026-10-02: ui-viz는 참고 자료이며 최종 기준은 현재 HM 구현과 이 문서다(작업 지시). 개별 수치에 대한 별도 결정은 없다.
|
|
|
|
## 11. 미확정 / 보류
|
|
|
|
- 수치(240px, padding, 12px 글자)는 현재 HM 규격이며 디자인 확정 시 재검토.
|
|
- delay: shadcn 기본 0 유지. HM delay 규칙은 없다.
|
|
- Motion 규칙은 정의되지 않아 shadcn 기본 animation 유지.
|
|
- 비활성 control에 붙이는 방식은 소비 조합(wrapper element).
|
|
|
|
## 12. 관련 파일
|
|
|
|
```
|
|
packages/ui/src/components/ui/tooltip.tsx
|
|
packages/ui/src/theme/tooltip.css
|
|
packages/ui/src/theme.css (import)
|
|
packages/ui/src/index.ts (export)
|
|
src/components/tooltip.stories.tsx
|
|
```
|
|
|
|
## 13. 검증 상태
|
|
|
|
- 2026-10-08: 공개 패키지 빌드·타입 검사 통과. Browser에서 mouse `PointerEvent`로 단독 사용, 상위/중첩 HM Provider delay, Root override, 그룹 skip-delay·만료·0 설정과 pointer leave를 검증했다. 실제 키보드로 focus·blur·Escape, controlled `open`/`onOpenChange`, `asChild`·ref, 비활성 wrapper를 확인했다. 주요 computed style은 수정 전과 동일하다. 실제 마우스 이동을 통한 hover는 별도 미검증이다.
|
|
- `npm run typecheck`, `npm run build`: 통과(2026-10-02).
|
|
- 실제 interaction(Browser pane): keyboard focus로 열림(`role=tooltip` 확인), Escape 닫힘.
|
|
- computed style: bg `rgb(10,34,29)`, text white, radius 4px, padding 6px 10px, 12/18, arrow fill 같은 색.
|
|
- 미확인: 실제 pointer hover 열림·pointer leave 닫힘, 긴 텍스트 줄바꿈 시각, 4방향 placement 시각, 비활성 wrapper trigger.
|