Common Components - kookmin-sw/capstone-2025-44 GitHub Wiki

📦 공통 컴포넌트 문서

Relevant Source Files

📚 문서 목적

타임페이 전역에서 재사용되는 UI 컴포넌트를 문서화한 것입니다. 이 컴포넌트들은 일관된 UI/UX를 유지하고, 개발 생산성을 높이기 위해 제작되었습니다.

1️⃣ Modal 컴포넌트

용도: 화면 위에 겹쳐서 표시되는 오버레이. 확인창, 폼 입력 등에 사용.

주요 구성 요소:

Modal: 메인 모달 컴포넌트
Modal.Title: 제목 표시 컴포넌트
Modal.Button: 하단 버튼
CloseButton: 닫기 버튼 (X 또는 뒤로가기 아이콘)

특징:

포탈 기반 렌더링 (body 최상단에 표시)
페이드/슬라이드 애니메이션
bottomFixed 옵션으로 하단 고정 가능

사용 예시:

<Modal onClose={handleClose} icon="back" bottomFixed={true}>
  <Modal.Title text="확인 요청\n정말 진행하시겠습니까?" />
  <p>이 작업은 되돌릴 수 없습니다.</p>
  <Modal.Button onClick={handleConfirm}>확인</Modal.Button>
</Modal>

관련 소스:

modal.tsx (30~72)

2️⃣ Bottom Sheet 컴포넌트

용도: 화면 하단에서 올라오는 UI 요소. 보조 작업 또는 추가 옵션 입력 시 사용.

구성 요소:

BottomSheet
내부 레이아웃: HeaderContainer, ContentContainer
프레이머 모션 애니메이션 사용

특징:

포탈 기반 렌더링
자동 높이 조절
헤더에 닫기 버튼 포함

관련 소스:

bottom-sheet.tsx (10~76)

3️⃣ Input 컴포넌트

3-1) InputBox

기능: 숫자 입력과 지도 검색 기능 등 특수 입력 지원

서브 컴포넌트:

InputNum: 숫자 입력
InputMap: 지도/검색 입력 (에러 애니메이션 포함)

관련 소스:

Input-box.tsx (10~119)

3-2) CommonInput

기능: 일반 숫자 입력 + 에러 처리, min/max 제한 등

서브 컴포넌트: InputInner

특징:

유효성 검사 실패 시 에러 상태로 변경 (색상/애니메이션 적용)
5초 후 에러 상태 자동 해제

관련 소스:

common-input.tsx (9~103)

4️⃣ Toggle Switch 컴포넌트

4-1) ToggleSwitch

기능: 두 가지 상태를 전환할 수 있는 UI

Props:

firstText, secondText: 라벨
onChangeSelected: 상태 변경 함수
isLeftSelected: 현재 선택 상태

관련 소스:

toggle-switch.tsx (8~71)

4-2) ToggleSwitchVer2

기능: 헤더에 적합하도록 라운드 탑 스타일 적용된 변형 버전

관련 소스:

toggle-switch-ver2.tsx (7~69)

5️⃣ Text 컴포넌트

PostingBoldText

포스팅 화면에서 강조 텍스트 출력용 스타일 컴포넌트

const PostingBoldText = styled.span`
  margin: 2.22rem 0px 2.5rem 0px;
  font-size: 1.67rem;
  color: black;
  text-align: center;
`;

관련 소스:

posting-bold-text.tsx (1~8)

6️⃣ 특수 컴포넌트: BirthModal

설명: 생년월일 입력을 위한 다단계 모달. Modal을 기반으로 구현됨.

입력 흐름:

연도 입력 → 유효성 검사
월 입력 → 유효성 검사
일 입력 → 유효성 검사
모든 항목 통과 후 완료 버튼으로 모달 닫기

특징:

단계별 자동 포커싱
에러 시 애니메이션 + 메시지 출력
상태 업데이트 및 유효성 검사 포함

관련 소스:

birth-modal.tsx (36~185)

7️⃣ 타입 정의

공통 타입은 `` 파일에 정의되어 있습니다.

타입 이름	설명	사용 위치
`BottomSheetProps`	BottomSheet 컴포넌트 props	열림/닫힘 상태 관리
`InputType`	입력 컴포넌트 공통 props	값 관리 및 에러 처리
`ToggleType`	토글 버튼 props	상태 및 라벨 정의
`SwitchToggleType`	토글 스위치 props	스타일 커스터마이징
`InputWrapperProps`	입력 컨테이너용 props	래퍼 설정
`InputInnerProps`	내부 입력 관련 props	유효성 검사, 레이아웃

관련 소스:

type.ts (23~92)

✅ Best Practices

입력 값 종류에 맞는 컴포넌트를 사용하세요.
모든 입력에는 유효성 검사 및 명확한 에러 메시지를 적용하세요.
Modal.Title, Modal.Button처럼 컴파운드 컴포넌트 패턴을 활용하세요.
에니메이션은 일관성 있게 사용하세요.
접근성(ARIA 등)을 고려한 상호작용 구현을 권장합니다.

Common Components - kookmin-sw/capstone-2025-44 GitHub Wiki

📦 공통 컴포넌트 문서

Relevant Source Files

📚 문서 목적

1️⃣ Modal 컴포넌트

2️⃣ Bottom Sheet 컴포넌트

3️⃣ Input 컴포넌트

3-1) InputBox

3-2) CommonInput

4️⃣ Toggle Switch 컴포넌트

4-1) ToggleSwitch

4-2) ToggleSwitchVer2

5️⃣ Text 컴포넌트

6️⃣ 특수 컴포넌트: BirthModal

7️⃣ 타입 정의

✅ Best Practices

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️