<!-- 함수 설계서. 작성: [AI] Architect. -->

# 함수 설계서: BottomSheet snap 정책 (#319)

> **상태**: Approved <!-- Draft | Approved | Superseded -->
> **작성**: [AI] Architect · **최종수정**: 2026-06-15
> **추적성** — Redmine: #319 / 부모 #301 · 관련 컴포넌트: `frontend/src/components/BottomSheet.tsx`

## 1. 책임

모바일 BottomSheet의 **3-snap 점착(snap) 점**과 **닫힘 임계 속도**를 정의하고, 사용자의 드래그 제스처가 어느 snap에 안착할지 결정하는 알고리즘을 명세한다.

## 2. 상수 (매직 넘버)

| 상수 | 값 | 의미 |
|------|----|------|
| `SNAP_POINTS.PEEK` | `0.4` | 초기/맨 아래 snap. 화면 높이의 40%만 시트가 보임 — 지도와 시트를 함께 보는 균형. |
| `SNAP_POINTS.HALF` | `0.55` | 중간 snap. 시트 콘텐츠 핵심(이름·평점·리뷰 첫 줄)이 잘 보이는 위치. |
| `SNAP_POINTS.FULL` | `0.92` | 거의 풀 화면. 8% 여백은 상단 스와이프 핸들·상태바를 위해 남김. |
| `VELOCITY_THRESHOLD` | `0.5` (vh/s) | 빠른 아래 스와이프 감지 기준. 초당 화면 높이의 50% 이상이면 "닫기 의도"로 간주. |
| `CLOSE_BELOW_RATIO` | `0.6 × PEEK` ≈ 0.24 | snap 후보 중 PEEK의 60% 아래로 끌어내리면 강제 닫힘. |

## 3. 결정 알고리즘 (`snapTo(height, velocity)`)

```
입력: height(현재 높이 ratio 0~1), velocity(아래 방향 vh/s, 양수=아래)

1. velocity > VELOCITY_THRESHOLD && height < HALF  →  onClose()
2. height < CLOSE_BELOW_RATIO                       →  onClose()
3. 그 외: [PEEK, HALF, FULL] 중 height와 최단 거리인 점에 setHeight()
```

## 4. 왜 이 값들인가 (근거)

- **0.4/0.55/0.92**: 모바일 UX 가이드(Material/iOS BottomSheet)의 30%/50%/95% 패턴을 한국 식당 카드 콘텐츠 길이(이름 18px + 평점 16px + 영상 썸네일 200px 기준)에 맞춰 조정.
- **0.5 vh/s**: 일반 손가락 플릭 속도가 0.7~1.2 vh/s, 의도적인 닫기 스와이프 임계점.
- **0.24 close-below**: PEEK(0.4)의 60% — 우발적 드래그(<0.05) 차단 + 의도적 닫기(<0.24) 수용.

## 5. 변경 시 주의

- 사용자의 근육 기억(스와이프 거리 감각) 교란 위험이 있어 SNAP_POINTS 변경은 ADR로 분리할 것.
- VELOCITY_THRESHOLD를 낮추면 의도치 않은 닫힘 ↑, 높이면 닫기 어려움 ↑.

## 6. 테스트 권고

- `snapTo(0.45, 0.1)` → HALF로 안착
- `snapTo(0.2, 0.7)` → onClose 호출
- `snapTo(0.85, 0)` → FULL로 안착
- `snapTo(0.1, 0)` → onClose 호출 (CLOSE_BELOW_RATIO)
- 단위 테스트는 `utils/bottomSheetSnap.ts`로 함수 추출 후 #343에서 진행.

## 7. 미해결 질문

- 가로 모드 / 큰 폰트 접근성 모드에서 PEEK가 너무 작아 보이는 케이스 — 향후 동적 조정 검토.
