# Component Decision Tree

유사한 역할의 PDS 컴포넌트 중 어느 것을 써야 하는지의 판단 기준을 모은 가이드. prop/API 비교가 아니라 **사용 상황과 의도** 기준으로 정리한다.

> 컴포넌트의 prop 정의·타입·기본값은 **Guide / Composition Patterns** 페이지와 각 컴포넌트의 `.props.txt`(Tier 1)를 참조하라. 본 가이드는 _어느 컴포넌트를 쓸지_만 다룬다.

---

## 1. 단일 선택 — `Radio` / `RadioGroup` / `BoxRadioGroup` / `SegmentedControl`

모두 단일 선택이지만 레이아웃 방향과 선택이 즉시 반영되느냐가 다르다. `Switch`는 on/off 이진 상태 전환이라 이 그룹과 목적이 달라 별도 취급한다.

| 판단 기준 | `Radio` / `RadioGroup` | `BoxRadioGroup` | `SegmentedControl` | | ----------------------- | ---------------------- | --------------- | ------------------- | | 레이아웃 방향 | 가로 / 세로 | 가로 / 그리드 | 가로 고정 | | 옵션 수 | 제한 없음 | 2~6개 권장 | 2~5개 | | 선택 결과 반영 시점 | 폼 제출 후 | 폼 제출 후 | 즉각 반영 (뷰 전환) | | 아이콘/이미지가 포함된 옵션 | 불가 | 불가 | 가능 | | 옵션 helper text | 가능 | 가능 | 불가 | | 주요 사용 위치 | 폼, 설정 | 필터, 옵션 선택 | 뷰 전환, 탭 대체 |

**선택 가이드**

-   폼 안에서 가로/세로 배치로 단일 선택 → `Radio` / `RadioGroup`
-   선택지를 카드형으로 시각 강조하거나 가로 배치 → `BoxRadioGroup`
-   선택 즉시 콘텐츠가 전환되어야 할 때 → `SegmentedControl`

---

## 2. 탭 — `LineTabs` / `PanelTabs` / `BoxTabs`

탭 컴포넌트는 사용 위계와 시각적 강조 수준으로 구분한다.

| 판단 기준 | `LineTabs` | `PanelTabs` | `BoxTabs` | | ----------------- | ----------- | ----------- | ---------------------------- | | 사용 위계 | 페이지 레벨 | 섹션 레벨 | 섹션 레벨 | | 스타일 | 밑줄 | 패널 배경 | 박스형 배경 | | 상단 고정(sticky) | 가능 | 불가 | 불가 | | 탭 수 | 2~7개 | 2~8개 | 제한 없음 (사용자 추가 가능) |

**선택 가이드**

-   페이지 전체의 주요 네비게이션 → `LineTabs`
-   카드/패널 내부 콘텐츠 전환 → `PanelTabs`
-   탭 자체를 버튼처럼 강조해야 할 때, 또는 사용자가 직접 탭을 추가하는 경우 → `BoxTabs`

---

## 3. 보조 정보 표시 — `Tooltip` / `Popover`

두 컴포넌트 모두 hover와 click 트리거를 지원한다. 구분 기준은 트리거 방식이 아니라 **콘텐츠 복잡도**다.

| 판단 기준 | `Tooltip` | `Popover` | | ---------------------------- | -------------------------- | ------------------------- | | 트리거 | hover / click 모두 지원 | hover / click 모두 지원 | | 콘텐츠 타입 | 텍스트만 | 텍스트 + 복합 콘텐츠 가능 | | 내부 인터랙션 (버튼·링크 등) | 불가 | 가능 | | 레이아웃 옵션 | 단일 | short form / long form | | `kind` (의미적 변형) | neutral / accent / negative | — | | 모바일 사용 | 가능 | 가능 |

**선택 가이드**

-   짧은 텍스트 정보만 표시하고 내부 인터랙션이 필요 없을 때 → `Tooltip`
-   버튼·링크·복합 콘텐츠가 포함될 때 → `Popover`
-   모바일 환경에서 추가 정보가 필요하면 `Tooltip`보다 `Popover` 사용 (모바일은 hover가 안정적이지 않다)

---

## 4. Modal 계열 — 유형 선택

PDS의 모달은 5개 유형으로 구성된다. 각 유형은 **사용 조건**으로 구분한다.

| 유형 | 컴포넌트 / 호출 | 주요 목적 | 버튼 구성 | | -------- | ------------------------------------------------------------ | ----------------------------------- | ----------- | | Alert | `await Alert(\{...\})` (`AlertModal` 함수형 호출) | 오류·경고 등 즉각 인지 필요 | 단일 확인 | | Confirm | `await Confirm(\{...\})` (`ConfirmModal` 함수형 호출) | 사용자 의사 결정 요청 | 취소 + 확인 | | Basic | `\<Modal opened=\{...\} onCancel=\{...\}\>` (JSX 직접) | 범용 콘텐츠 표시 | 상황에 따라 | | Notice | `\<NoticeModal opened=\{...\} onCancel=\{...\}\>` (JSX 직접) | 공지·프로모션 등 이미지가 포함된 콘텐츠 | 상황에 따라 | | Floating | `\<FloatingModal trigger=\{...\}\>` (JSX 직접, 트리거 기반) | 화면 일부 위에 떠있는 형태 | 상황에 따라 |

**유형 선택 가이드**

| 유형 | 사용 조건 | Do | Don't | | ------- | ---------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- | | Alert | 특정 행동의 결과를 알릴 때 | 필요한 최소한의 기능만 담는다. 오류는 `kind="error"` 사용 | "확인 / 닫기 / X" 같은 동일 기능 버튼 중복. title과 heading에 동일 정보 중복 | | Confirm | 행동에 대한 의사를 물어볼 때 | 필요한 최소한의 기능만 담는다 | "취소 / X" 동일 기능 버튼 중복. 불필요한 title 사용 | | Basic | 항목의 상세 내역을 보여줄 때 | contents area에 정보를 자유롭게 담되 정해진 스펙 안에서 | 정해진 스펙 외 임의 커스텀(X 버튼 제거 등) |

**`Modal` (Basic) 사이즈 가이드**

| 사이즈 | 너비 | 사용 시점 | | -------- | ------ | --------------------------------------------------- | | `xlarge` | 1280px | 좌우에 테이블이 2개 있는 등 확장된 형태가 필요할 때 | | `large` | 900px | 조회용 테이블이 있는 경우 | | `medium` | 720px | 달력·작은 테이블·이미지 등이 들어갈 때 | | `small` | 480px | 간단한 정보를 입력해야 할 때 | | `xsmall` | 375px | 모바일 미리보기를 보여줄 때 |

---

## 5. Modal 계열 — 오버레이 유형 선택

같은 오버레이라도 `Modal` / `BottomSheet` / `Drawer`는 진입 방향과 플랫폼 맥락이 다르다.

| 판단 기준 | `Modal` | `BottomSheet` | `Drawer` | | ----------- | ------------------------------------------- | --------------------- | ---------------------- | | 주 플랫폼 | 웹 / 데스크톱 | 모바일 | 웹 / 데스크톱 | | 진입 방향 | 중앙 팝업 | 하단에서 위로 | 좌/우 측면 | | 주요 목적 | 확인 / 경고 / 정보 표시 | 추가 옵션 / 상세 정보 | 네비게이션 / 상세 패널 | | 콘텐츠 길이 | 짧음 권장 | 스크롤 가능 | 스크롤 가능 | | 변형 유형 | Alert / Confirm / Basic / Notice / Floating | regular / full | — | | Backdrop | 항상 | 항상 | 항상 |

**선택 가이드**

-   사용자의 즉각적인 확인/결정이 필요한 경우 → `Modal` (또는 함수형 `Alert()` / `Confirm()`)
-   모바일에서 하단으로 추가 정보나 옵션을 제공할 때 → `BottomSheet`
-   측면에서 슬라이드로 펼쳐 네비게이션이나 상세를 보여줄 때 → `Drawer`

---

## 참고 가이드

-   합성 패턴 (portal·slots·subcomponent 등): **Guide / Composition Patterns** 페이지
-   prop 정의·타입·기본값: 각 컴포넌트의 `resources/components/component-\{slug\}.props.txt`