ScheduleCalendar

메인 캘린더 컴포넌트입니다. Month / Week / Day / List 뷰를 포함합니다.

Props

prop	타입	기본값	필수	설명
schedules	Schedule[]	—	✅	표시할 일정 목록 (부모가 scope·CRUD 반영 후 전달)
holidays	Holiday[] | undefined	—		사내 기념일 등 — API 결과와 병합됩니다
fetchPublicHolidays	boolean	false		공공데이터포털 공휴일 API 자동 조회. 기본 false — 사용하려면 명시적으로 true를 전달하세요. true이면 date v-model 기준 연도별 1회만 요청합니다.
publicHolidayServiceKey	string | undefined	—		공공데이터포털 인증키 — proxy/BFF 사용 시 생략. 직접 외부 API URL 호출 시에만 전달합니다.
hideToolbar	boolean | undefined	—		true이면 뷰 전환 툴바(Month / Week / Day / List)를 숨깁니다. 부모가 v-model:view로 뷰를 직접 제어하는 임베딩 시나리오에서 사용합니다.
scheduleTypeOptions	ScheduleTypeOption[] | undefined	—		일정 유형 목록 — 칩·바의 색상과 List 뷰 라벨에 사용됩니다. 기본값은 SCHEDULE_TYPE_OPTIONS (my/team/company 3종). 커스텀 타입을 추가하려면 기본값을 spread 후 항목을 추가하세요: [...SCHEDULE_TYPE_OPTIONS, { type: 'project', label: '프로젝트', color: '...', backgroundColor: '...' }]
monthWeekCount	MonthWeekCount	6		월간 뷰에 표시할 주(week) 수 — 기본 6(전체 월). 2|3이면 date v-model 기준 선택 날짜가 포함된 주부터 축소 표시합니다.
weekdayLabels	string[] | undefined	—		월간 뷰 요일 헤더 라벨 (일~토 순서 7개). 명시하면 locale 자동 현지화보다 우선 적용됩니다. 기본 영문 축약형 (SUN~SAT).
startHour	number | undefined	—		Week/Day 시간 그리드 시작 시각 (0~23) — 기본 0
endHour	number | undefined	—		Week/Day 시간 그리드 종료 시각 (0~23) — 기본 23
locale	string | undefined	—		Intl.DateTimeFormat locale (예: 'ko-KR') — 월간 뷰 요일 헤더, Week/Day 요일 라벨을 자동 현지화합니다. weekdayLabels를 명시하면 월간 뷰는 그 값이 우선합니다. 브라우저 Intl API 기반이라 zero-dep 유지.
displayTimezone	string | undefined	—		표시 타임존(F4-8) — IANA 타임존 이름(예: 'America/New_York'). 미지정 시 브라우저 시스템 타임존(기존 동작, 100% 하위호환). Month/Week/Day/List의 날짜 배치·시간 위치·"오늘" 판정에 반영됩니다. v1 제약: 일정 생성(드래그 슬롯 선택)·드래그 이동/리사이즈는 계속 브라우저 로컬 기준입니다(v1.1 예정). Intl.DateTimeFormat이 인식하지 못하는 이름을 넘기면 개발 모드에서 경고 후 브라우저 로컬로 폴백합니다.

v-model

v-model	타입	기본값	설명
v-model:view	CalendarView	"month"	현재 뷰 (Month/Week/Day/List)
v-model:date	Date	startOfDay(new Date())	현재 선택 날짜
v-model:listFilterDate	Date | null	null	List 뷰 날짜 필터 — null이면 필터 없음(선택 월 전체 표시)
v-model:viewScope	ViewScope	"company"	View Option — My / Company 필터
v-model:scheduleTypes	string[] | null	null	일정 유형 필터 — null이면 전체 유형, 빈 배열이면 결과 없음

Emits

emit	payload	설명
view-change	CalendarViewChangePayload	Month/Week/Day/List 탭 클릭
date-select	CalendarDateSelectPayload	월간 셀, Week 날짜 헤더 클릭
overflow-click	CalendarOverflowClickPayload	월간 +N 클릭
schedule-click	CalendarScheduleClickPayload	칩·All Day 바·시간 일정·List 행 클릭
navigate	CalendarNavigatePayload	Today·‹›(이전/다음) 버튼 클릭 — Month/Week/Day
list-filter-clear	—	List 뷰 날짜 필터 바 Clear 클릭
query-change	ScheduleQueryChangePayload	View Option·Schedule Type·기간 포함 — 부모 API 조회용
time-slot-select	CalendarTimeSlotSelectPayload	Week/Day 시간 그리드 빈 셀 클릭 — 일정 생성 등에 start/end 전달
schedule-move	CalendarScheduleMovePayload	Week/Day 시간 그리드 — 드래그로 이벤트 이동 확정
schedule-resize	CalendarScheduleResizePayload	Week/Day 시간 그리드 — 드래그로 이벤트 end 시각 리사이즈 확정

Slots

상세 slot props 필드는 architecture.md § Scoped Slots 참고.

slot	props 타입	설명
#toolbar	ToolbarSlotProps	뷰 전환 UI 전체를 대체합니다. 기본 콘텐츠는 CalendarToolbar(Month/Week/Day/List 탭).
#day-cell	DayCellSlotProps	월간 셀 내부 콘텐츠(날짜 숫자·이벤트 목록)를 대체합니다. role="gridcell" 셸은 유지됩니다.
#event	EventSlotProps	칩·All Day 바·시간 그리드 블록의 표시 콘텐츠를 대체합니다. 클릭/DnD 인터랙션 래퍼는 유지됩니다.
#month-overflow-item	MonthOverflowItemSlotProps	월간 +N 팝오버 목록 항목의 콘텐츠를 대체합니다.
#list-cell-no	ListCellSlotProps	List 뷰 No 컬럼 셀 내부 콘텐츠를 대체합니다. 행 클릭·키보드 인터랙션은 유지됩니다 (REV-A3).
#list-cell-title	ListCellSlotProps	List 뷰 Title 컬럼 셀 내부 콘텐츠를 대체합니다.
#list-cell-type	ListCellSlotProps	List 뷰 Type 컬럼 셀 내부 콘텐츠를 대체합니다.
#list-cell-participant	ListCellSlotProps	List 뷰 Participant 컬럼 셀 내부 콘텐츠를 대체합니다.
#list-cell-period	ListCellSlotProps	List 뷰 Period 컬럼 셀 내부 콘텐츠를 대체합니다.

이 표는 ScheduleCalendar.vue의 타입에서 vue-component-meta로 자동 생성됩니다(F3-2) — prop/emit/slot을 추가·변경했는데 이 표가 갱신되지 않는 문서 drift를 CI가 차단합니다. 직접 수정하지 말고 pnpm --filter @vuepkg/calendar run docs:api로 재생성하세요.

CalendarView 타입

type CalendarView = 'month' | 'week' | 'day' | 'list'

사용 예

<script setup lang="ts">
import { ref } from 'vue'
import { ScheduleCalendar, useScheduleCalendarHost } from '@vuepkg/calendar'
import type { Schedule } from '@vuepkg/calendar'

const schedules = ref<Schedule[]>([])
const { view, date, calendarListeners } = useScheduleCalendarHost({
  onQueryChange({ range }) {
    // API 호출: range.start ~ range.end 범위 일정 조회
  },
})
</script>

<template>
  <div style="height: 700px;">
    <ScheduleCalendar
      v-model:view="view"
      v-model:date="date"
      :schedules="schedules"
      v-bind="calendarListeners"
    />
  </div>
</template>