Working time & dates
Working hours, date overrides, duration units, and date-input helpers.
Usage
import type { GanttCalendar } from "@art-tools/react-gantt";
const calendar: GanttCalendar = {
hours: ["9:00-12:00", "13:00-17:00"],
days: { 0: false, 6: false },
dates: { "2026-01-01": false },
};
// <Gantt tasks={tasks} calendar={calendar} durationUnit="hour" />- Supplying calendar opts into working-time scheduling. Without it, scheduling uses linear time. Calendar precedence is dates, then days, then hours. Omitted hours means the full day; false marks a day off.
- Hours use local civil time with minute precision, such as 8:30-12:00. Ranges are half-open; 24:00 is allowed only as an end. Weekdays run from 0 (Sunday) to 6 (Saturday). Date keys use YYYY-MM-DD.
- snapToWorking defaults to true. Setting it to false disables snapping of library-authored dates, while working-time duration arithmetic and non-working shading remain in effect. Consumer-supplied dates are not rewritten merely by supplying a calendar.
- With a working calendar, one durationUnit day uses the longest working weekday in the week. Working-time walks use civil dates, including across daylight-saving changes.
- displayEndDate is for displaying an inclusive last day. endInstantFromDisplayDate converts a chosen whole-day end to the following local midnight. Preserve exact stored instants when an editor leaves a date unchanged.
GanttCalendar
TypeThe chart's working-time calendar. Three scopes resolve in the order `dates` → `days` → `hours`, so a specific date beats a weekday rule, which beats the global default. Passing a calendar at all is the opt-in: with no `calendar` prop the chart schedules in plain linear time exactly as it did before this feature existed. The object may be written inline — it is keyed by content, not identity, so a fresh-but-equal object on every render costs nothing.
| Property | Type & description |
|---|---|
hoursOptional | DayHoursWorking hours for every day with no override below. Omitted means the *full* day (`"0:00-24:00"`), so a calendar that only lists weekend days off stays day-granular rather than silently acquiring business hours. |
daysOptional | Partial<Record<Weekday, DayHours>>Per-weekday override. Beats GanttCalendar.hours. |
datesOptional | Record<string, DayHours>Per-date override keyed by local civil date, `"YYYY-MM-DD"`. Beats both GanttCalendar.days and GanttCalendar.hours. Use it for holidays (`false`), half days, or a one-off working Saturday. |
TypeScript declaration
/**
* The chart's working-time calendar. Three scopes resolve in the order
* `dates` → `days` → `hours`, so a specific date beats a weekday rule, which
* beats the global default.
*
* Passing a calendar at all is the opt-in: with no `calendar` prop the chart
* schedules in plain linear time exactly as it did before this feature existed.
*
* The object may be written inline — it is keyed by content, not identity, so a
* fresh-but-equal object on every render costs nothing.
*/
export declare interface GanttCalendar {
/**
* Working hours for every day with no override below. Omitted means the
* *full* day (`"0:00-24:00"`), so a calendar that only lists weekend days off
* stays day-granular rather than silently acquiring business hours.
*/
hours?: DayHours;
/** Per-weekday override. Beats {@link GanttCalendar.hours}. */
days?: Partial<Record<Weekday, DayHours>>;
/**
* Per-date override keyed by local civil date, `"YYYY-MM-DD"`. Beats both
* {@link GanttCalendar.days} and {@link GanttCalendar.hours}. Use it for
* holidays (`false`), half days, or a one-off working Saturday.
*/
dates?: Record<string, DayHours>;
}DayHours
TypeWorking hours for a single day, or `false` for a day off. Gaps *between* ranges are non-working — that is how a lunch break is expressed: `["8:00-12:00", "13:00-17:00"]`.
/**
* Working hours for a single day, or `false` for a day off. Gaps *between*
* ranges are non-working — that is how a lunch break is expressed:
* `["8:00-12:00", "13:00-17:00"]`.
*/
export declare type DayHours = WorkTimeRange[] | false;WorkTimeRange
TypeA span of working hours within one day, `"H:MM-H:MM"` in local civil time with minute precision — e.g. `"8:30-12:00"`. Half-open: the end minute is the first non-working minute. `"24:00"` is legal only as an end.
/**
* A span of working hours within one day, `"H:MM-H:MM"` in local civil time with
* minute precision — e.g. `"8:30-12:00"`. Half-open: the end minute is the first
* non-working minute. `"24:00"` is legal only as an end.
*/
export declare type WorkTimeRange = string;Weekday
Type`0` = Sunday … `6` = Saturday, matching `Date.prototype.getDay`.
/** `0` = Sunday … `6` = Saturday, matching `Date.prototype.getDay`. */
export declare type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;DurationUnit
TypeThe unit an input `duration` is expressed in, and the unit it displays in.
/** The unit an input `duration` is expressed in, and the unit it displays in. */
export declare type DurationUnit = "day" | "hour" | "minute";NonWorkingReason
TypeWhy a column is shaded. Weekend vs holiday matters only for styling.
/** Why a column is shaded. Weekend vs holiday matters only for styling. */
export declare type NonWorkingReason = "weekend" | "holiday" | "offHours";displayEndDate
FunctionThe inclusive last-occupied civil day, for **display only**. Stored dates are exclusive instants, which reads wrong in a column: a task running Monday through Friday stores Saturday. This converts back for humans — the day containing the last worked moment. Never write the result back to a task.
/**
* The inclusive last-occupied civil day, for **display only**.
*
* Stored dates are exclusive instants, which reads wrong in a column: a task
* running Monday through Friday stores Saturday. This converts back for humans —
* the day containing the last worked moment. Never write the result back to a task.
*/
export declare function displayEndDate(startDate: Date, endInstant: Date): Date;endInstantFromDisplayDate
FunctionInverse of displayEndDate for a whole-day edit: the exclusive instant starting the day after `displayEnd`. This is what a `<input type="date">` end-date editor needs — the user picks the last day they mean, and the task stores the following midnight.
/**
* Inverse of {@link displayEndDate} for a whole-day edit: the exclusive instant
* starting the day after `displayEnd`.
*
* This is what a `<input type="date">` end-date editor needs — the user picks the
* last day they mean, and the task stores the following midnight.
*/
export declare function endInstantFromDisplayDate(displayEnd: Date): Date;