배율과 테마 타입

이 페이지는 타임라인을 재는 방법과 차트의 색을 정하는 다섯 가지 타입을 다뤄요. GanttScaleKey는 다섯 배율 중 하나예요. GanttScaleFormat과 GanttFormatOverrides는 한 배율의 라벨을 바꾸고, GanttTheme은 팔레트를 고르고, Holiday는 주말 외의 휴일을 표시해요. 다섯 타입 모두 패키지 루트에서 내보내요.

import type {
  GanttScaleKey,
  GanttScaleFormat,
  GanttFormatOverrides,
  GanttTheme,
  Holiday,
} from '@jaeungkim/gantt-chart';

GanttScaleKeyCopy Anchor Link

export type GanttScaleKey = 'day' | 'week' | 'month' | 'quarter' | 'year';

선언 순서가 배율 순서예요. 가장 촘촘한 배율이 먼저 와요. Ctrl/Cmd + ArrowUp은 한 단계 촘촘한 배율로, Ctrl/Cmd + ArrowDown은 한 단계 성긴 배율로 옮기고 양쪽 끝에서 멈춰요. zoomOnWheel을 켜면 Ctrl/Cmd + 휠도 같은 순서를 따라가요. defaultScale은 이 값 중 하나를 받고 기본값은 'month'예요.

차트는 배율 선택기를 그리지 않아요. 다시 마운트하면 배율도 기억하지 않고요. 선택기가 필요하면 앱에서 직접 그리고 ref의 setScale로 배율을 바꾸세요. 휠과 키보드를 포함한 모든 변경은 onScaleChange로 전달돼요. GanttHandle을 참고하세요.

formats는 이 키로 묶이고 GanttDetailRenderProps.scale도 이 값을 담아요. 상세 렌더러를 참고하세요.

배율별 설정Copy Anchor Link

키 하나는 고정된 표의 한 행에 대응해요. 그 행이 헤더 셀의 라벨, 눈금 하나가 덮는 시간, 드래그 한 단계의 픽셀 수를 정해요. 배율마다 무엇을 보여 주는지는 타임라인에 있고 이 페이지는 한 행의 타입만 다뤄요.

export interface GanttScaleConfig {
  labelUnit: GanttLabelUnit;
  tickUnit: 'minute' | 'hour' | 'day' | 'week' | 'month';
  unitPerTick: number;
  /** 칸 하나가 `tickUnit` 여러 개를 담을 때 첫 칸을 맞추는 경계예요 */
  tickAlign?: GanttLabelUnit;

  dragStepUnit: 'minute' | 'hour' | 'day' | 'week';
  dragStepAmount: number;

  basePxPerDragStep: number;

  formatTickLabel: (date: Dayjs) => string;
  formatHeaderLabel: (date: Dayjs) => string;
}

/** 상단 헤더 행이 묶는 단위 ('quarter'는 dayjs에 대응하는 단위가 없어요 - core/dates 참고) */
export type GanttLabelUnit =
  | 'hour'
  | 'day'
  | 'week'
  | 'month'
  | 'quarter'
  | 'year';

GanttScaleConfig와 GanttLabelUnit, GANTT_SCALE_CONFIG 객체는 모듈 내부에만 있고 패키지에서 내보내지 않아요. 이 표는 가져오거나 확장하거나 교체할 수 없고 여섯 번째 배율을 추가하는 prop도 없어요. 눈금 너비는 basePxPerDragStep / dragStepAmount로 나와요. 그렇게 나온 하루당 픽셀 수는 타임라인에 있어요. 같은 두 필드가 정하는 드래그 그리드는 작업 편집에 있고요.

기본 라벨Copy Anchor Link

formatTickLabel과 formatHeaderLabel은 라벨 체인의 마지막 층이에요. formats 재정의와 locale이 모두 없을 때 이 값이 그려져요.

firstDayOfWeek를 설정하면 week 배율은 헤더를 day 행에서 가져와요.

툴팁 문자열과 드래그 표시 문자열은 각각 DATE_FORMATS와 RANGE_FORMATS 상수에 있고 둘 다 내보내지 않아요. day 행의 두 문자열에 들어간 [UTC]는 dayjs가 이스케이프한 리터럴이에요. 해석된 시간대 이름은 아니에요.

툴팁 문자열은 차트의 범용 날짜 라벨이에요. 호버 툴팁과 막대의 ARIA 라벨, 드래그와 키보드 알림, 기본 상세 패널의 Start와 End 필드에 모두 이 문자열이 표시돼요. 상세 패널은 두 필드를 편집할 수 없을 때만 이 문자열을 써요. 편집할 수 있는 필드는 YYYY-MM-DD를 보여 주는 네이티브 <input type="date">예요. 상세 패널을 참고하세요.

드래그 표시 문자열은 헤더의 드래그 날짜 표시에 쓰이는 배율별 축약형이에요. 차트가 이 값을 어디에 적는지와 짧은 문자열이 연도를 빼는 이유는 로케일과 날짜 형식에 있어요.

GanttScaleFormatCopy Anchor Link

/**
 * 한 배율에서 생성된 라벨을 대체해요
 * 모든 항목은 선택이에요 - 빼놓은 항목은 기본 라벨(또는 locale 라벨)을 그대로 써요
 */
export interface GanttScaleFormat {
  /** 하단 헤더 행 - 눈금마다 라벨 하나 */
  tick?: (date: Dayjs) => string;
  /** 상단 헤더 행 - 그룹마다 라벨 하나 */
  header?: (date: Dayjs) => string;
  /**
   * 차트가 날짜 하나로 적는 모든 자리: 막대의 호버 툴팁, 드래그 중 읽히는 값과 aria-label,
   * 헤더의 드래그 가이드 라벨(이 슬롯을 따라가는 `edge`와 `range`를 거쳐서), 그리고 상세
   * 패널의 Start와 End 중 편집할 수 없는 것. 편집할 수 있는 날짜는 네이티브
   * `<input type="date">`라서 포매터를 거치지 않아요.
   */
  tooltip?: (date: Dayjs) => string;
}

세 슬롯은 서로 따로 결정돼요. header만 넘기면 tick과 tooltip은 locale이나 기본 라벨이 만든 값 그대로 남아요.

tooltip 재정의는 헤더 드래그 날짜 표시의 양 끝에도 적용돼요. 재정의가 없으면 기본 라벨 표의 드래그 표시 열에 있는 배율별 축약 문자열을 그대로 써요.

GanttFormatOverridesCopy Anchor Link

/** 배율별 라벨 재정의, 예: `{ quarter: { header: (d) => ... } }` */
export type GanttFormatOverrides = Partial<
  Record<GanttScaleKey, GanttScaleFormat>
>;

formats prop의 타입이에요. 레코드에서 빠진 배율은 결정된 라벨을 그대로 유지해요.

const formats: GanttFormatOverrides = {
  quarter: {
    header: (d) => `${d.year()} Q${Math.floor(d.month() / 3) + 1}`,
  },
  month: {
    tooltip: (d) => d.format('YYYY-MM-DD'),
  },
};

formats는 렌더링마다 동일성이 유지되도록 모듈 스코프에 선언했어요. 세 라벨에서 어느 층이 이기는지와 동일성이 왜 중요한지는 로케일과 날짜 형식에 있어요.

GanttThemeCopy Anchor Link

/** 차트 테마 - 'system'은 OS 설정을 따라요. prop을 생략하면 호스트 페이지의 `color-scheme`을 따라가요. */
export type GanttTheme = 'light' | 'dark' | 'system';

theme prop의 타입이고 기본값은 없어요. 결정된 값이 컨테이너의 data-theme에 쓰이고 스타일시트는 그 속성을 읽어요. 값이 어떻게 결정되는지와 팔레트에 무엇이 들어 있는지는 테마에 있어요.

GanttTheme은 값이 셋인 유니온이고 모든 색은 CSS 커스텀 속성이에요. 테마 객체나 토큰 prop은 없어요.

HolidayCopy Anchor Link

/** 주말 말고도 쉬는 날. 그냥 `YYYY-MM-DD` 문자열이면 라벨 없는 같은 것이에요. */
export interface Holiday {
  /** UTC `YYYY-MM-DD` */
  date: string;
  /** 마지막 날 포함 - 하루짜리면 생략해요 */
  endDate?: string;
  /** 띠가 담을 만큼 넓을 때, 그 위 눈금 행에 적히는 글자 */
  label?: string;
  /** 아무 CSS 색이나 - 주말 음영과 같은 세기로 격자에 덧입혀요. 덮어 칠하지는 않아요. */
  color?: string;
}

차트가 휴일을 어떻게 그리는지, 라벨이 언제 보이는지, 항목을 어떻게 넘기는지는 타임라인에 있어요.

참고Copy Anchor Link

세 슬롯이 어떻게 결정되는지와 각 포매터가 무엇을 받는지, 객체 동일성 규칙은 로케일과 날짜 형식에 있어요.

• GanttScaleFormat 함수는 string을 반환해야 해요. ReactNode를 반환할 수는 없고 헤더 셀을 대체하는 prop도 없어요. 헤더 셀은 텍스트라서 .gantt-top-group과 .gantt-bottom-cell에 CSS를 주면 생김새를 바꿀 수 있어요.
• 차트가 쓰는 UTC dayjs 인스턴스는 패키지에서 내보내지 않아요. 재정의에 같은 인스턴스가 필요하면 dayjs와 utc 플러그인을 직접 불러오세요.