Web - Calendar (Added in 2.2)

Added in 2.2

Definition

정의	Calendar
최적화 대상	Desktop Mobile → 모바일 전용 캘린더 고려중
기획 배포	진행 중
디자인 가이드 배포	진행 중
개발 코드 배포	진행 중

Principle

Calendar는 날짜 및 시간 단위로 일정을 생성/확인/편집할 수 있는 컴포넌트입니다. 주로 일정, 예약, 태스크 관리 등에 사용되며, 다양한 뷰 타입과 인터렉션을 제공합니다.

DatePicker와의 차이는,
Calendar는 시간의 흐름을 구조적으로 보여주면서, 일정(이벤트 등)을 배치하거나 조회/관리할 수 있는 컴포넌트이고
DatePicker는 날짜(및 시간)를 선택할 수 있게 해주는 간단한 입력형 컴포넌트입니다.

따라서, 인풋 계열에 날짜를 선택하는 것에는 DatePicker를 사용하고, 일정을 조회하고 관리하거나 편집하는 곳엔 Calendar를 씁니다.

Spec

캘린더 컴포넌트의 책임 범위 → 뷰를 그리고, 이벤트를 심을 수 있다. 실제 액션부터는 pApp이 책임진다?

캘린더 디자인 스펙을 대략적으로 정리해두겠지만, 작업자분이 큰 틀을 만들고 디테일을 잡아가는 것으로 하고자 합니다.
구글 캘린더, 애플 캘린더, 노션 캘린더와 같이 우리가 익숙하게 볼 수 있는 형태라고 생각하시면 됩니다.

캘린더 반응형 (데스크톱 내에서 반응형. 모바일은 별도의 컴포넌트 고려 중)
- 캘린더는 컨테이너에 맞춰 유동적(responsive)이어야 함
- 월간/주간/일간/연간 모두 같은 컴포넌트 안에서 전환 가능해야 함
'오늘' 날짜 강조
- 오늘에 해당하는 날짜는 스타일로 강조 (ex. 테두리, 컬러 등)
- 캘린더 열릴 때 기본 포커스는 오늘 기준으로 맞춰짐
지난 날짜는 클릭할 수 없는 상태로 비활성화되어야 할 수 있습니다.
타임존에 대한 표시와 관리가 필요할 수 있습니다.
뷰 타입
- 월간, 주간, 일간, 연간
- 각각의 뷰에 따라 일정 표현 방식과 시간 단위 레이아웃이 다름
종일 / 시간 단위 일정 구분
- 일간/주간 뷰: 상단에 종일, 하단에 시간 영역 분리 → 명시적으로 영역 구분
- 월간 뷰: 상단에 종일 배치, 나머지 시간 단위 배치
n개 더보기
- 월간 보기에서 한 칸에 들어갈 수 있는 일정 개수는 화면 사이즈에 따라 달라짐
- 초과 시 "n개 더보기" 형태로 제공되어야 함
일정 인터랙션 → 수정 필요
- 클릭: 날짜/일정 클릭 가능 (onClick)
- 더블 클릭: 일정 생성/편집 등 (onDoubleClick)
- 드래그: 범위 선택 또는 이동 (onDrag)
- 키: delete로 삭제 등 (onKeyDown)

→ 이 모든 건 property로 제공하여 사용 여부에 따라 사용할 수도 안할 수도 있어야합니다.

이것 이외에 빠진 것들 있다면 제안주시면 좋을 것 같습니다.

Calendar 컴포넌트를 적극적으로 쓰고자 하는 곳은 “티켓 pApp”입니다. 티켓에서 Calendar를 적극적으로 쓰고자 하는 기능은 다음과 같습니다. (캘린더 구현 우선순위 참고용)

Copy of SW - E00002HallSchedule (v3.0) 문서 참고
주간과 월간 캘린더 존재
종일/시간 구분 필요 없음. 무조건 시간 단위로만 존재함
단일 선택, 벌크 선택(shift+click), delete 키
‘오늘’ 선택하여 오늘에 해당되는 날짜로 돌아오고 포커스 됨

영역 구분

내용

Calendar Header

타이틀

Copy of Web - TextLabel 참고
- styleTheme : headingBold

오늘 표현 영역

이전/다음 이동 버튼
- Copy of Web - IconButton 참고
  - baseSize : small
  - baseColorKey : ui_cpnt_button_fill_base_transparent
  - iconName
    - ic_arrow_left (지난 일/달/월)
    - ic_arrow_right (이후 일/달/월)
  - iconSize : 16
  - iconColorKey : ui_cpnt_icon_sys_grey_01
‘오늘’ 텍스트 버튼
- Copy of Web - TextButton 참고
  - size : small
  - colorTheme : grey_01
  - text : str_31

캘린더 뷰 전환

Copy of Web - Dropdown (Added in 1.3) 참고
- size : small
- defaultValue : 기본 뷰 값에 맞춘 값 보여짐 (일, 주, 월, 년)
- valueArray
  - 일 : str_fm_day
  - 주 : str_fm_week
  - 월 : str_fm_month
  - 년 : str_fm_year

Weekday Label

요일 텍스트

Copy of Web - TextLabel 참고
- styleTheme : caption2Bold
- colorTheme : sysTextSecondary
- textAlign : center

면적 영역

height : 32px
width : responsive

Calendar Body

날짜 텍스트

Copy of Web - TextLabel 참고
- styleTheme
  - 현재 :
    caption2Bold
  - 나머지 : caption2Regular
- colorTheme
  - 현재 : sysTextPrimary
  - (월 뷰일 때) 이전/다음 달 : sysTextTertiary
- textAlign : center

면적 영역

월 뷰 기준
- grid min-width : 64px
- grid min-height : 64px

→ 이렇게 가져가는 것이 맞을지 / 캘린더 전체의 크기를 이야기하는게 맞을지..

추가된 일정 표현

종일 일 때
- 선택 전
  - 면적 (Div)
    - width
    - 월간일 때 : 날짜 너비 양 옆 4px 간격 두고 responsive
    - height
      - 월간일 때 : 텍스트 높이값에 따름
      - 주간/일간일 때 : 시간에 맞춰서 유동적
    - radius : 4
    - ui_cpnt_sheet_base
  - 텍스트 Copy of Web - TextLabel
    - styleTheme : caption2Regular
- 선택 후
  - 면적
    - 기획 의도에 따라 컬러키를 다양하게 부여할 수 있음. 우선 ui_cpnt_sheet_base_06 컬러 부여
  - 텍스트Copy of Web - TextLabel
    - styleTheme : caption2Regular
    - colorTheme : sysTextWhite
시간 단위일 때
- 선택 전
  - 면적
    - 면적 영역 사이즈는 종일과 동일하나 ui_cpnt_sheet_base_03 적용
  - dot 표현
    - 4px 원형
    - 기획 의도에 따라 컬러키를 다양하게 부여할 수 있음. 우선 ui_cpnt_icon_sys_grey_02 컬러 부여
  - 텍스트Copy of Web - TextLabel
    - styleTheme : caption2Regular
    - colorTheme : sysTextWhite
- 선택 후
  - 면적
    - 기획 의도에 따라 컬러키를 다양하게 부여할 수 있음. 우선 ui_cpnt_sheet_base_06 컬러 부여
  - dot
    - ui_cpnt_icon_sys_white
  - 텍스트Copy of Web - TextLabel
    - styleTheme : caption2Regular
    - colorTheme : sysTextWhite

Properties

defaultViewType

캘린더 뷰의 기본값을 설정합니다.

기획 지시사항

기획서 상 작성 방법 : Enum Values 중 하나를 사용함

Type	`enum`
Default	`'month'`

Enum Values Description
`'day'`	일 캘린더
`'week'`	주 캘린더
`'month'`	월 캘린더
`'year'`	년 캘린더

viewType

캘린더에서 제공할 뷰를 작성합니다.

기획 지시사항

기획서 상 작성 방법 : 순서값 나열함

Type

ex. [month, week]

day, week, month, year 중 보여질 순서를 나열하여 작성

Default

-

displayAllDayEventsMode (추후?)

종일 이벤트 상단 표현 여부를 결정합니다. * 주/일 캘린더일 때

기획 지시사항

기획서 상 작성 방법 : Enum Values 중 하나를 사용함

Type	`enum`
Default	`'none'`

Enum Values Description
`'none'`	사용 안함
`'use'`	사용함

timeGridInterval → 이건 개인화된 설정으로 풀어야할 수도. PDS 차원으로 강제로 제공하지 않음!

~~이벤트 생성 시간의 기본 단위를 결정합니다.~~

기획 지시사항

기획서 상 작성 방법 : Enum Values 중 하나를 사용함

Type	`enum`
Default	`'30min'`

Enum Values Description
`'15min'`	~~15분 단위로 설정~~
`'30min'`	~~30분 단위로 설정~~
`'60min'`	~~60분 단위로 설정~~

startOfWeek

시작 요일을 결정합니다.

기획 지시사항

기획서 상 작성 방법 : Enum Values 중 하나를 사용함

Type	`enum`
Default	`'sunday'`

Enum Values Description
`'sunday'`	일요일부터 시작합니다.
`'monday'`	월요일부터 시작합니다.

todayBtnMode

오늘에 해당하는 날짜로 빠르게 이동할 수 있는 버튼을 표시합니다.

기획 지시사항

기획서 상 작성 방법 : Enum Values 중 하나를 사용함

Type	`enum`
Default	`'none'`

Enum Values Description
`'none'`	사용하지 않음
`'use'`	사용함

+

캘린더 기획 시, 다음 사항을 기획해라.

${TARGET}을 ${ACTION}하면, ${UI}가 ${TRIGGER} 됨

TARGET : 일정(schedule) / 날짜(date)
ACTION : 'CLICK' 'CLICK_WITH_SHIFT_KEY_DOWN' 'DELETE_KEY_DOWN'
- 액션 추가가 필요하다면, PDS 작업자와 논의할 것
UI : 선택적인 것, 액션이 발생했을 때 어떤 UI를 띄울지 결정할 수 있다.
TRIGGER : 캘린더 인터렉션 이후 각 기획 사항에 맞춰 발생해야하는 사항

문서 작성 정보

소유자 / 관리자	김혜진
변경 이력	2025/06/06 : 문서 최초 작성 - 김혜진