[✨ Feature] 모달 Surface 공통 컴포넌트 구현

[Lseojeong]

📌 설명

서비스 전반에서 일관된 방식으로 모달과 패널을 사용할 수 있도록 공통 Surface 컴포넌트를 구현합니다.

Surface를 Root로 하는 Compound Pattern을 적용하여 모달과 패널을 동일한 인터페이스로 사용할 수 있도록 구성합니다.
모달은 Overlay를 함께 사용할 수 있고, 패널은 Overlay 없이 화면 우측에 표시되도록 지원합니다.

ESC 키 및 외부 영역 클릭 시 닫기 기능을 제공하며, 작성 중인 Surface는 canClose, closeOnEscape, closeOnOutsideClick 옵션을 통해 의도치 않게 닫히지 않도록 제어할 수 있습니다.

공통 Button 컴포넌트와 조합할 수 있도록 Trigger, Close는 asChild 패턴을 지원합니다.

🛠️ 구현 목록 (TODO)

Surface

• Surface 기반 Compound Pattern 구현
• variant="modal" 지원
• variant="panel" 지원
• Panel은 Overlay 없이 표시 가능
• Controlled / Uncontrolled 지원
• Open / Close 상태 관리
• canClose 기반 닫기 정책 지원

Compound Pattern

• Surface Root 구현
• Surface.Trigger 구현
• Surface.Portal 구현
• Surface.Overlay 구현
• Surface.Content 구현
• Surface.Header 구현
• Surface.Body 구현
• Surface.Footer 구현
• Surface.Close 구현
• Trigger, Close에서 asChild 지원

Interaction

• ESC 키 닫기 Hook 구현
• Click Outside 닫기 Hook 구현
• canClose=false일 때 Outside Click 닫기 차단
• canClose=false일 때 ESC 닫기 차단
• closeOnEscape 옵션 지원
• closeOnOutsideClick 옵션 지원
• Close 버튼은 동일한 닫기 정책을 따르도록 구현
• 여러 Surface가 동시에 열렸을 때 최상단 Surface만 interaction 처리

접근성

• Focus Trap 적용
• Focus Restore 지원
• role="dialog" 적용
• Modal variant에서 aria-modal 적용
• aria-label 또는 aria-labelledby 타입 필수화
• icon-only Surface.Close의 aria-label 타입 필수화
• Trigger에 aria-controls, aria-expanded 자동 연결
• Scroll Lock 지원
• Modal 기본 Scroll Lock 적용

스타일

• 중앙 Modal 스타일 구현
• 우측 Panel 스타일 구현
• z-index.css로 z-index 토큰 관리

문서화

• Storybook 작성
• TSDoc 작성

✅ 참고

디자인 링크, 관련 이슈 등 (선택)

• Radix UI Dialog
• 웹 접근성(WAI-ARIA Dialog Pattern)