Schedule

일정 관리를 위한 캘린더 컴포넌트

개요

Schedule은 FullCalendar를 기반으로 Day/Week/WorkWeek/Month/Agenda 뷰, 드래그 & 리사이즈, Collapse 래핑, 카테고리 색상 등을 지원하는 일정 관리 컴포넌트입니다.

주요 특징

• ✅ 다양한 뷰: Day, Week, WorkWeek, Month, Agenda(목록) 뷰 지원
• ✅ 드래그 & 리사이즈: 이벤트 드래그 이동 및 시간 조절
• ✅ Collapse 래핑: title prop으로 접기/펼치기 UI 제공
• ✅ 카테고리 색상: categoryColors로 이벤트 배경색 일괄 설정
• ✅ 읽기 전용: readOnly prop으로 편집 차단
• ✅ 네비게이션: 이전/다음/오늘 버튼, 날짜 선택기, 이동 범위 제한(minDate/maxDate)
• ✅ 요약 팝업: 일정 클릭 시 요약 + 편집/삭제 (showEventPopup)
• ✅ 셀 제스처 분기: 클릭/더블클릭/드래그를 각각 다른 통로로 통지
• ✅ 형식과 문구 분리: locale은 날짜 형식, labels는 UI 문구

기본 사용

events를 전달하면 주간 뷰로 일정이 표시됩니다.

import { Schedule } from "@vortex/ui-cals"
 
const events = [
  {
    id: "1",
    title: "팀 미팅",
    start: new Date(2025, 6, 17, 10, 0),
    end: new Date(2025, 6, 17, 11, 0),
  },
]
 
<Schedule events={events} currentView="week" height={500} />

뷰 모드

views prop으로 표시할 뷰를 지정하고, currentView로 현재 뷰를 제어합니다.

뷰를 바꾸면 캘린더를 새로 만듭니다. 전환 직후 스크롤 위치는 초기화됩니다.

const [currentView, setCurrentView] = useState<ScheduleViewMode>("week")
 
<Schedule
  events={events}
  views={["day", "week", "workWeek", "month", "agenda"]}
  currentView={currentView}
  onViewChange={setCurrentView}
/>

드래그 & 리사이즈

allowEventDrag로 일정 이동과 시간 조절을 엽니다.

구 prop allowDragAndDrop · allowResizing 은 아직 동작합니다. 다음 메이저에서 제거되니 allowEventDrag 로 옮겨 주세요. 둘 다 넘기면 allowEventDrag 가 우선합니다.

<Schedule
  events={events}
  allowEventDrag
  onEventChange={(data) => {
    console.log(data.event.title, data.changes)
  }}
/>

Collapse 래핑

title prop을 지정하면 Collapsible로 래핑됩니다.

<Schedule
  title="일정 관리"
  events={events}
  collapsed={collapsed}
  onCollapseChange={setCollapsed}
/>

카테고리 색상

categoryColors로 이벤트의 categoryField 값에 따라 배경색을 일괄 지정합니다.

<Schedule
  events={[
    { id: "1", title: "미팅", start: new Date(), categoryField: "meeting" },
    { id: "2", title: "휴가", start: new Date(), categoryField: "holiday" },
  ]}
  categoryColors={[
    { value: "meeting", color: "#4f46e5" },
    { value: "holiday", color: "#dc2626" },
  ]}
/>

요약 팝업

일정을 클릭하면 요약 팝업이 열립니다(기본 동작). onEventEdit·onEventDelete를 넘긴 경우에만 해당 버튼이 나타납니다. showEventPopup={false}로 끌 수 있습니다.

<Schedule
  events={events}
  onEventEdit={(event) => openEditor(event)}
  onEventDelete={(event) => remove(event.id)}
/>

빈 셀 제스처

빈 셀의 클릭·더블클릭·드래그는 각각 다른 통로로 올라옵니다. 세 콜백 모두 선택 사항이며, 넘기지 않으면 선택 표시만 되고 아무 동작도 하지 않습니다.

<Schedule
  events={events}
  onCellClick={(data) => openQuickAdd(data.start)}
  onCellDoubleClick={(data) => openFullForm(data.start)}
  onCellSelect={(data) => {
    // data.gesture: "click" | "doubleClick" | "drag"
    if (data.gesture === "drag") openRangeForm(data.start, data.end)
  }}
/>

형식과 문구

세 축은 따로입니다. locale은 날짜·요일·시간 형식(Intl·date-fns), labels는 화면 문구, timezone은 일정이 그리드에 놓이는 시간대입니다. 기본 문구는 한국어이며, 영어가 필요하면 SCHEDULE_EN_LABELS를 넘깁니다.

import { Schedule, SCHEDULE_EN_LABELS } from "@vortex/ui-cals"
 
// 전부 영어
<Schedule events={events} locale="en-US" labels={SCHEDULE_EN_LABELS} />
 
// 앱의 i18n 사전에서 필요한 것만
<Schedule
  events={events}
  labels={{ today: t("calendar.today"), views: { month: t("calendar.month") } }}
/>

일정 우클릭

onEventContextMenu로 일정 우클릭을 받습니다. 핸들러를 넘긴 경우에만 브라우저 기본 메뉴를 막습니다. 무엇을 할지는 앱이 정합니다 — 삭제 확인, 자체 컨텍스트 메뉴 등.

<Schedule
  events={events}
  onEventContextMenu={(event, nativeEvent) => {
    openMenuAt(nativeEvent.clientX, nativeEvent.clientY, event)
  }}
/>

구 prop onContextDelete는 아직 동작합니다. 다음 메이저에서 제거되니 onEventContextMenu로 옮겨 주세요. 둘 다 넘기면 onEventContextMenu만 불립니다.

API Reference

Props

ScheduleViewMode

type ScheduleViewMode = "day" | "week" | "workWeek" | "month" | "agenda"

ScheduleEvent

ScheduleCategoryColor

ScheduleDateSelectData

ScheduleCellSelectData

ScheduleDateSelectData에 제스처가 붙은 형태입니다.

ScheduleLabelOverrides

ScheduleLabels의 부분 집합입니다. 지정한 항목만 기본 한국어 문구를 대체합니다.

<Schedule labels={{ today: "Today", views: { month: "Month" } }} />

미리 만들어 둔 묶음: SCHEDULE_KO_LABELS(기본), SCHEDULE_EN_LABELS.

ScheduleEventChangeData

접근성

권장 사항

• ✅ Foundation FullCalendar 내부에서 role="grid" 시맨틱 자동 적용
• ✅ 네비게이션 버튼에 aria-label 제공 (이전, 다음, 오늘)
• ✅ 이벤트 요소에 포커스 및 키보드 접근 가능
• ✅ 로딩 시 aria-busy="true" 자동 적용
• ❌ 색상만으로 카테고리를 구분하지 말고 title/body에 카테고리 정보를 포함할 것을 권장

관련 컴포넌트

• Foundation FullCalendar: 기반 캘린더 프리미티브
• DateTimePicker: 날짜/시간 입력 컴포넌트