@quartzio/gantt 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/API.md +533 -0
- package/LICENSE +21 -0
- package/README.md +83 -2
- package/dist/index.d.ts +1341 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +6556 -0
- package/dist/index.js.map +1 -0
- package/dist/styles.css +1299 -0
- package/package.json +51 -3
- package/src/calendar/duration.ts +42 -0
- package/src/calendar/project.ts +29 -0
- package/src/calendar/workingCalendar.ts +218 -0
- package/src/data/draft.ts +78 -0
- package/src/data/graph.ts +215 -0
- package/src/data/normalize.ts +661 -0
- package/src/data/operations.ts +112 -0
- package/src/data/project.ts +194 -0
- package/src/data/serialize.ts +26 -0
- package/src/data/transaction.ts +460 -0
- package/src/data/tree.ts +156 -0
- package/src/data/types.ts +229 -0
- package/src/index.ts +139 -0
- package/src/scheduling/schedule.ts +310 -0
- package/src/styles.css +1299 -0
- package/src/timeaxis/align.ts +120 -0
- package/src/timeaxis/format.ts +72 -0
- package/src/timeaxis/presets.ts +219 -0
- package/src/timeaxis/timeAxis.ts +205 -0
- package/src/util/civil.ts +38 -0
- package/src/util/emitter.ts +53 -0
- package/src/util/equal.ts +23 -0
- package/src/util/errors.ts +4 -0
- package/src/util/parse.ts +70 -0
- package/src/util/time.ts +18 -0
- package/src/util/zone.ts +303 -0
- package/src/view/bars.ts +63 -0
- package/src/view/binding.ts +162 -0
- package/src/view/cellEditor.ts +239 -0
- package/src/view/cells.ts +89 -0
- package/src/view/columns.ts +197 -0
- package/src/view/createGantt.ts +1164 -0
- package/src/view/dates.ts +14 -0
- package/src/view/dependencies.ts +147 -0
- package/src/view/editing.ts +303 -0
- package/src/view/history.ts +72 -0
- package/src/view/interaction.ts +671 -0
- package/src/view/keyboard.ts +149 -0
- package/src/view/listWidth.ts +201 -0
- package/src/view/menu.ts +265 -0
- package/src/view/nonWorking.ts +113 -0
- package/src/view/range.ts +41 -0
- package/src/view/rows.ts +235 -0
- package/src/view/selection.ts +156 -0
- package/src/view/taskActions.ts +71 -0
- package/src/view/taskEditor.ts +553 -0
- package/src/view/timeline.ts +155 -0
- package/src/view/tooltip.ts +117 -0
- package/src/view/types.ts +328 -0
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
import { toTime } from '../data/normalize';
|
|
2
|
+
import type { DateInput, ProjectState } from '../data/types';
|
|
3
|
+
import { assertLocale } from '../timeaxis/format';
|
|
4
|
+
import { resolvePreset, type ViewPreset } from '../timeaxis/presets';
|
|
5
|
+
import { createTimeAxis, type TimeAxis } from '../timeaxis/timeAxis';
|
|
6
|
+
import { isEqual } from '../util/equal';
|
|
7
|
+
import { QuartzioError } from '../util/errors';
|
|
8
|
+
import { defaultTimelineRange } from './range';
|
|
9
|
+
import type { HeaderState, Viewport } from './types';
|
|
10
|
+
|
|
11
|
+
/** Assumed viewport width before it has been measured (and when rendering on the server). */
|
|
12
|
+
export const UNMEASURED_WIDTH = 1200;
|
|
13
|
+
|
|
14
|
+
export interface TimelineOptions {
|
|
15
|
+
preset: ViewPreset;
|
|
16
|
+
startDate: DateInput | undefined;
|
|
17
|
+
endDate: DateInput | undefined;
|
|
18
|
+
locale: string | undefined;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
interface TimelineOptionsInput {
|
|
22
|
+
preset?: string | ViewPreset | undefined;
|
|
23
|
+
startDate?: DateInput | null | undefined;
|
|
24
|
+
endDate?: DateInput | null | undefined;
|
|
25
|
+
locale?: string | undefined;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Validates the timeline options; throws QuartzioError before anything is changed. */
|
|
29
|
+
export function resolveTimeline(options: TimelineOptionsInput): TimelineOptions {
|
|
30
|
+
const preset = resolvePreset(options.preset);
|
|
31
|
+
if (options.locale !== undefined) assertLocale(options.locale);
|
|
32
|
+
// `null` from plain JavaScript means "not set", like `undefined`.
|
|
33
|
+
const startDate = options.startDate ?? undefined;
|
|
34
|
+
const endDate = options.endDate ?? undefined;
|
|
35
|
+
// The format doesn't depend on the zone, so check it now; the real value is read in the project's zone.
|
|
36
|
+
const start = toTime(startDate, 'startDate', 'Gantt options', 'UTC');
|
|
37
|
+
const end = toTime(endDate, 'endDate', 'Gantt options', 'UTC');
|
|
38
|
+
if (start !== null && end !== null && end <= start) {
|
|
39
|
+
throw new QuartzioError('Gantt options: "endDate" must be after "startDate".');
|
|
40
|
+
}
|
|
41
|
+
return { preset, startDate, endDate, locale: options.locale };
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
const dateValue = (value: DateInput | undefined): unknown =>
|
|
45
|
+
value instanceof Date ? value.getTime() : value;
|
|
46
|
+
|
|
47
|
+
/** Equal by value, so re-rendering with a new but equal Date (or an equal custom preset) is no change. */
|
|
48
|
+
export const sameTimeline = (a: TimelineOptions, b: TimelineOptions): boolean =>
|
|
49
|
+
(a.preset === b.preset || isEqual(a.preset, b.preset)) &&
|
|
50
|
+
Object.is(dateValue(a.startDate), dateValue(b.startDate)) &&
|
|
51
|
+
Object.is(dateValue(a.endDate), dateValue(b.endDate)) &&
|
|
52
|
+
a.locale === b.locale;
|
|
53
|
+
|
|
54
|
+
/** Parses an already validated date option, falling back when it isn't set. Never throws. */
|
|
55
|
+
function parseOr(value: DateInput | undefined, zone: string, fallback: number): number {
|
|
56
|
+
try {
|
|
57
|
+
return toTime(value, 'date', 'Gantt options', zone) ?? fallback;
|
|
58
|
+
} catch {
|
|
59
|
+
return fallback;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export interface TimelineView {
|
|
64
|
+
axisFor: (project: ProjectState, viewportWidth: number, timeline: TimelineOptions) => TimeAxis;
|
|
65
|
+
headerFor: (axis: TimeAxis, viewport: Viewport, rowHeight: number) => HeaderState;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Derives the time axis and the visible header cells. Each piece is reused while its inputs are unchanged,
|
|
70
|
+
* and nothing here throws: options are validated up front, and oversized ranges are cut short.
|
|
71
|
+
*/
|
|
72
|
+
export function createTimelineView(): TimelineView {
|
|
73
|
+
let rangeCache: { key: unknown[]; range: { start: number; end: number } } | undefined;
|
|
74
|
+
const timelineRange = (
|
|
75
|
+
project: ProjectState,
|
|
76
|
+
timeline: TimelineOptions,
|
|
77
|
+
): { start: number; end: number } => {
|
|
78
|
+
const key = [project.tasks, project.settings, timeline];
|
|
79
|
+
if (!rangeCache || key.some((part, i) => part !== rangeCache?.key[i])) {
|
|
80
|
+
const zone = project.settings.timeZone;
|
|
81
|
+
const fallback = defaultTimelineRange(project, timeline.preset, Date.now());
|
|
82
|
+
const start = parseOr(timeline.startDate, zone, fallback.start);
|
|
83
|
+
const end = parseOr(timeline.endDate, zone, fallback.end);
|
|
84
|
+
rangeCache = { key, range: { start, end: Math.max(start, end) } };
|
|
85
|
+
}
|
|
86
|
+
return rangeCache.range;
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
let axisCache: { key: unknown[]; axis: TimeAxis } | undefined;
|
|
90
|
+
const axisFor = (project: ProjectState, viewportWidth: number, timeline: TimelineOptions): TimeAxis => {
|
|
91
|
+
const { start, end } = timelineRange(project, timeline);
|
|
92
|
+
const { timeZone, weekStartsOn } = project.settings;
|
|
93
|
+
const { preset, locale } = timeline;
|
|
94
|
+
const minWidth = viewportWidth > 0 ? viewportWidth : UNMEASURED_WIDTH;
|
|
95
|
+
// Keyed on the tick count needed to fill the viewport, so resizing by a few pixels reuses the axis.
|
|
96
|
+
const key = [start, end, preset, locale, timeZone, weekStartsOn, Math.ceil(minWidth / preset.tickWidth)];
|
|
97
|
+
if (axisCache && key.every((part, i) => part === axisCache?.key[i])) return axisCache.axis;
|
|
98
|
+
|
|
99
|
+
const axis = createTimeAxis({
|
|
100
|
+
start,
|
|
101
|
+
end,
|
|
102
|
+
preset,
|
|
103
|
+
timeZone,
|
|
104
|
+
weekStartsOn,
|
|
105
|
+
locale,
|
|
106
|
+
minWidth,
|
|
107
|
+
truncate: true,
|
|
108
|
+
});
|
|
109
|
+
// Different inputs can still produce the same axis (e.g. the last task moved by an hour). Keeping the
|
|
110
|
+
// old object lets everything memoized on it stay valid.
|
|
111
|
+
const previous = axisCache?.axis;
|
|
112
|
+
const same =
|
|
113
|
+
previous?.start === axis.start &&
|
|
114
|
+
previous.end === axis.end &&
|
|
115
|
+
previous.tickCount === axis.tickCount &&
|
|
116
|
+
previous.preset === axis.preset &&
|
|
117
|
+
previous.locale === axis.locale &&
|
|
118
|
+
previous.timeZone === axis.timeZone &&
|
|
119
|
+
previous.weekStartsOn === axis.weekStartsOn;
|
|
120
|
+
axisCache = { key, axis: same ? previous : axis };
|
|
121
|
+
return axisCache.axis;
|
|
122
|
+
};
|
|
123
|
+
|
|
124
|
+
let headerCache:
|
|
125
|
+
{ axis: TimeAxis; rowHeight: number; from: number; to: number; header: HeaderState } | undefined;
|
|
126
|
+
const headerFor = (axis: TimeAxis, viewport: Viewport, rowHeight: number): HeaderState => {
|
|
127
|
+
const width = viewport.width > 0 ? viewport.width : UNMEASURED_WIDTH;
|
|
128
|
+
const visibleFrom = viewport.scrollLeft;
|
|
129
|
+
const visibleTo = viewport.scrollLeft + width;
|
|
130
|
+
if (
|
|
131
|
+
headerCache?.axis === axis &&
|
|
132
|
+
headerCache.rowHeight === rowHeight &&
|
|
133
|
+
headerCache.from <= visibleFrom &&
|
|
134
|
+
visibleTo <= headerCache.to
|
|
135
|
+
) {
|
|
136
|
+
return headerCache.header;
|
|
137
|
+
}
|
|
138
|
+
// Render one extra viewport on each side, so most scrolling reuses the same cells.
|
|
139
|
+
const from = Math.max(0, visibleFrom - width);
|
|
140
|
+
const to = Math.min(axis.totalWidth, visibleTo + width);
|
|
141
|
+
const rows = axis.preset.headers.map((_, row) => axis.headerCells(row, from, to));
|
|
142
|
+
const header: HeaderState = { rows, rowHeight, height: rows.length * rowHeight };
|
|
143
|
+
// At the timeline's edges the window can't grow, so treat it as open-ended there.
|
|
144
|
+
headerCache = {
|
|
145
|
+
axis,
|
|
146
|
+
rowHeight,
|
|
147
|
+
from: from === 0 ? Number.NEGATIVE_INFINITY : from,
|
|
148
|
+
to: to === axis.totalWidth ? Number.POSITIVE_INFINITY : to,
|
|
149
|
+
header,
|
|
150
|
+
};
|
|
151
|
+
return header;
|
|
152
|
+
};
|
|
153
|
+
|
|
154
|
+
return { axisFor, headerFor };
|
|
155
|
+
}
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import { getWorkingCalendar } from '../calendar/project';
|
|
2
|
+
import type { WorkingCalendar } from '../calendar/workingCalendar';
|
|
3
|
+
import { getTreeIndex } from '../data/tree';
|
|
4
|
+
import type { Id, ProjectState, Task } from '../data/types';
|
|
5
|
+
import type { TimeAxis } from '../timeaxis/timeAxis';
|
|
6
|
+
import { builtInText, type CellContext } from './columns';
|
|
7
|
+
import { taskDates } from './dates';
|
|
8
|
+
import { barUnder, type TimelinePoint } from './interaction';
|
|
9
|
+
import { rowKey, type RowsState } from './rows';
|
|
10
|
+
import type { Viewport } from './types';
|
|
11
|
+
|
|
12
|
+
/** The tooltip for the task under the pointer: what to show, and where. */
|
|
13
|
+
export interface TaskTooltip {
|
|
14
|
+
readonly taskId: Id;
|
|
15
|
+
/** Key of the task's row. */
|
|
16
|
+
readonly rowKey: string;
|
|
17
|
+
readonly task: Task;
|
|
18
|
+
readonly title: string;
|
|
19
|
+
/** Formatted values, in order. */
|
|
20
|
+
readonly fields: readonly { readonly label: string; readonly value: string }[];
|
|
21
|
+
/**
|
|
22
|
+
* Where it points to, in timeline coordinates: the start of the visible part of the bar (`align: 'start'`) or
|
|
23
|
+
* its end (`'end'`, the tooltip's right edge there).
|
|
24
|
+
*/
|
|
25
|
+
readonly x: number;
|
|
26
|
+
readonly align: 'start' | 'end';
|
|
27
|
+
/** The room (px) from `x` to the edge of the visible timeline it runs towards; `null` before measuring. */
|
|
28
|
+
readonly room: number | null;
|
|
29
|
+
/**
|
|
30
|
+
* The top of the row (the tooltip above it), or its bottom when `below`: when there's no room above it in the
|
|
31
|
+
* visible rows (the header would cover it) and more below.
|
|
32
|
+
*/
|
|
33
|
+
readonly y: number;
|
|
34
|
+
readonly below: boolean;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export interface TooltipView {
|
|
38
|
+
readonly project: ProjectState;
|
|
39
|
+
readonly timeAxis: TimeAxis;
|
|
40
|
+
readonly rows: RowsState;
|
|
41
|
+
readonly rowIds: readonly Id[];
|
|
42
|
+
readonly viewport: Viewport;
|
|
43
|
+
readonly locale: string | undefined;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* About how tall the default tooltip can get (a title and four lines, wrapped when there's little room), to
|
|
48
|
+
* decide whether it fits above a row. Below a row, there's room for it.
|
|
49
|
+
*/
|
|
50
|
+
const TOOLTIP_HEIGHT = 160;
|
|
51
|
+
|
|
52
|
+
/** The tooltip for a point, or `null`. Returns `previous` when it would show the same. Never throws. */
|
|
53
|
+
export function tooltipFor(
|
|
54
|
+
view: TooltipView,
|
|
55
|
+
point: TimelinePoint,
|
|
56
|
+
previous: TaskTooltip | null,
|
|
57
|
+
): TaskTooltip | null {
|
|
58
|
+
const hit = barUnder(view, point);
|
|
59
|
+
if (!hit) return null;
|
|
60
|
+
const { bar, index, taskId } = hit;
|
|
61
|
+
const task = view.project.tasks.byId.get(taskId);
|
|
62
|
+
const dates = task ? taskDates(task) : null;
|
|
63
|
+
if (!task || !dates) return null;
|
|
64
|
+
|
|
65
|
+
const { scrollLeft, width } = view.viewport;
|
|
66
|
+
const right = bar.x + bar.width; // a milestone's width is 0: its center
|
|
67
|
+
const visibleStart = Math.max(bar.x, scrollLeft);
|
|
68
|
+
const visibleEnd = width > 0 ? Math.min(right, scrollLeft + width) : right;
|
|
69
|
+
// Towards the side with more room, so it runs past the edge as little as possible (and is kept within it).
|
|
70
|
+
const roomAfter = scrollLeft + width - visibleStart;
|
|
71
|
+
const roomBefore = visibleEnd - scrollLeft;
|
|
72
|
+
const align = width > 0 && roomBefore > roomAfter ? 'end' : 'start';
|
|
73
|
+
const room = width > 0 ? Math.max(0, Math.round(align === 'end' ? roomBefore : roomAfter)) : null;
|
|
74
|
+
const rowHeight = view.rows.rowHeight;
|
|
75
|
+
const roomAbove = index * rowHeight - view.viewport.scrollTop;
|
|
76
|
+
const roomBelow =
|
|
77
|
+
view.viewport.height > 0
|
|
78
|
+
? view.viewport.scrollTop + view.viewport.height - (index + 1) * rowHeight
|
|
79
|
+
: Number.POSITIVE_INFINITY;
|
|
80
|
+
const below = roomAbove < TOOLTIP_HEIGHT && roomBelow > roomAbove;
|
|
81
|
+
const x = align === 'end' ? visibleEnd : visibleStart;
|
|
82
|
+
const y = below ? (index + 1) * rowHeight : index * rowHeight;
|
|
83
|
+
const same =
|
|
84
|
+
previous?.task === task &&
|
|
85
|
+
previous.x === x &&
|
|
86
|
+
previous.y === y &&
|
|
87
|
+
previous.align === align &&
|
|
88
|
+
previous.room === room;
|
|
89
|
+
if (same) return previous;
|
|
90
|
+
|
|
91
|
+
const cell: CellContext = {
|
|
92
|
+
task,
|
|
93
|
+
isParent: !getTreeIndex(view.project.tasks).isLeaf(taskId),
|
|
94
|
+
dates,
|
|
95
|
+
settings: view.project.settings,
|
|
96
|
+
locale: view.locale,
|
|
97
|
+
calendar: calendarOf(view.project),
|
|
98
|
+
};
|
|
99
|
+
const fields: TaskTooltip['fields'] =
|
|
100
|
+
bar.kind === 'milestone'
|
|
101
|
+
? [{ label: 'Date', value: builtInText('startDate', cell) }]
|
|
102
|
+
: [
|
|
103
|
+
{ label: 'Start', value: builtInText('startDate', cell) },
|
|
104
|
+
{ label: 'End', value: builtInText('endDate', cell) },
|
|
105
|
+
{ label: 'Duration', value: builtInText('duration', cell) },
|
|
106
|
+
{ label: 'Done', value: builtInText('percentDone', cell) },
|
|
107
|
+
];
|
|
108
|
+
return { taskId, rowKey: rowKey(taskId), task, title: task.name, fields, x, align, room, y, below };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
function calendarOf(project: ProjectState): WorkingCalendar | undefined {
|
|
112
|
+
try {
|
|
113
|
+
return getWorkingCalendar(project);
|
|
114
|
+
} catch {
|
|
115
|
+
return undefined;
|
|
116
|
+
}
|
|
117
|
+
}
|
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
import type { Transaction } from '../data/transaction';
|
|
2
|
+
import type { DateInput, Id, Patch, ProjectData, ProjectInput, ProjectState } from '../data/types';
|
|
3
|
+
import type { ViewPreset } from '../timeaxis/presets';
|
|
4
|
+
import type { HeaderCell, TimeAxis } from '../timeaxis/timeAxis';
|
|
5
|
+
import type { ColumnInput, ColumnsState } from './columns';
|
|
6
|
+
import type { DependencyLine } from './dependencies';
|
|
7
|
+
import type { ProposedChange, TaskInteraction, TimelineHit, TimelinePoint } from './interaction';
|
|
8
|
+
import type { HistoryState } from './history';
|
|
9
|
+
import type { CellEdit } from './editing';
|
|
10
|
+
import type { MenuCustomizer, MenuState, MenuTarget } from './menu';
|
|
11
|
+
import type { TaskEditorAction, TaskEditorState } from './taskEditor';
|
|
12
|
+
import type { KeyInput } from './keyboard';
|
|
13
|
+
import type { ListPaneState, ListResizeAction } from './listWidth';
|
|
14
|
+
import type { TimeSpan } from './nonWorking';
|
|
15
|
+
import type { RowsState } from './rows';
|
|
16
|
+
import type { KeyModifiers } from './selection';
|
|
17
|
+
import type { TaskTooltip } from './tooltip';
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* The visible part of the timeline body: its size (excluding the task list and the header) and the scroll
|
|
21
|
+
* position of the shared scroll area.
|
|
22
|
+
*/
|
|
23
|
+
export interface Viewport {
|
|
24
|
+
readonly width: number;
|
|
25
|
+
readonly height: number;
|
|
26
|
+
readonly scrollLeft: number;
|
|
27
|
+
readonly scrollTop: number;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface HeaderState {
|
|
31
|
+
/**
|
|
32
|
+
* Cells per header row (top to bottom), only around the visible part of the timeline. The arrays keep
|
|
33
|
+
* their identity while scrolling within the rendered window, so rows can be memoized.
|
|
34
|
+
*/
|
|
35
|
+
readonly rows: readonly (readonly HeaderCell[])[];
|
|
36
|
+
readonly rowHeight: number;
|
|
37
|
+
/** All header rows together. */
|
|
38
|
+
readonly height: number;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Everything a renderer needs to draw the chart. Plain data — no DOM, no framework types. */
|
|
42
|
+
export interface ViewState {
|
|
43
|
+
readonly viewport: Viewport;
|
|
44
|
+
readonly project: ProjectState;
|
|
45
|
+
readonly timeAxis: TimeAxis;
|
|
46
|
+
readonly header: HeaderState;
|
|
47
|
+
/** Columns of the task list on the left. */
|
|
48
|
+
readonly columns: ColumnsState;
|
|
49
|
+
/** Visible task rows (virtualized), in tree order, with their bars. */
|
|
50
|
+
readonly rows: RowsState;
|
|
51
|
+
/** Dependency arrows near the rendered rows (virtualized with them). */
|
|
52
|
+
readonly dependencies: readonly DependencyLine[];
|
|
53
|
+
/** Where "now" is on the timeline, or `null` when outside it (or turned off). */
|
|
54
|
+
readonly today: TodayLine | null;
|
|
55
|
+
/** Non-working time to shade, around the visible part of the timeline. */
|
|
56
|
+
readonly nonWorkingTime: readonly TimeSpan[];
|
|
57
|
+
/** What's being dragged, and where it would land; `null` when nothing is. */
|
|
58
|
+
readonly interaction: TaskInteraction | null;
|
|
59
|
+
/** Which drag interactions are on (from the options), e.g. to show their handles. The same object while unchanged. */
|
|
60
|
+
readonly interactions: Interactions;
|
|
61
|
+
/** Whether there's something to undo or redo. The same object while unchanged. */
|
|
62
|
+
readonly history: HistoryState;
|
|
63
|
+
/** Selected task ids, in the order they were selected. The same array while unchanged. */
|
|
64
|
+
readonly selection: readonly Id[];
|
|
65
|
+
/** The task the keyboard cursor is on, or `null`. */
|
|
66
|
+
readonly activeId: Id | null;
|
|
67
|
+
/** The tooltip for the task under the pointer, or `null`. The same object while it shows the same. */
|
|
68
|
+
readonly tooltip: TaskTooltip | null;
|
|
69
|
+
/** The cell being edited, or `null`. */
|
|
70
|
+
readonly editing: CellEdit | null;
|
|
71
|
+
/** The open context menu, or `null`. */
|
|
72
|
+
readonly menu: MenuState | null;
|
|
73
|
+
/** The open task editor, or `null`. */
|
|
74
|
+
readonly taskEditor: TaskEditorState | null;
|
|
75
|
+
/**
|
|
76
|
+
* Where the renderer should scroll to (after zooming, or to show a new task). A new object for each request:
|
|
77
|
+
* scroll when it changes.
|
|
78
|
+
*/
|
|
79
|
+
readonly scrollTo: ScrollRequest | null;
|
|
80
|
+
/** The task list's width, set with the divider between it and the timeline. */
|
|
81
|
+
readonly list: ListPaneState;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export interface ScrollRequest {
|
|
85
|
+
readonly left?: number;
|
|
86
|
+
readonly top?: number;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export interface Interactions {
|
|
90
|
+
readonly drag: boolean;
|
|
91
|
+
readonly resize: boolean;
|
|
92
|
+
readonly create: boolean;
|
|
93
|
+
readonly progress: boolean;
|
|
94
|
+
readonly link: boolean;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export interface TodayLine {
|
|
98
|
+
/** When the line was placed; it only moves once it reaches the next pixel. */
|
|
99
|
+
readonly time: number;
|
|
100
|
+
/** Whole pixels. */
|
|
101
|
+
readonly x: number;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Where a data change comes from: `'load'` is scheduling written back into data that was loaded (the initial
|
|
106
|
+
* data, or other data passed in), `'edit'` any edit (in the chart, or `transact`), `'undo'` and `'redo'` the
|
|
107
|
+
* history.
|
|
108
|
+
*/
|
|
109
|
+
export type GanttChangeSource = 'load' | 'edit' | 'undo' | 'redo';
|
|
110
|
+
|
|
111
|
+
export interface GanttDataChange {
|
|
112
|
+
readonly patch: Patch;
|
|
113
|
+
/** The project data with the change applied. */
|
|
114
|
+
readonly data: ProjectData;
|
|
115
|
+
/** Where the change comes from, e.g. to not mark a plan as unsaved for `'load'`. */
|
|
116
|
+
readonly source: GanttChangeSource;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export interface GanttOptions {
|
|
120
|
+
/**
|
|
121
|
+
* Controlled data. The engine never changes it on its own: edits are reported through `onChange`,
|
|
122
|
+
* and only show up once new `data` is passed back in.
|
|
123
|
+
*
|
|
124
|
+
* Having the `data` key makes the chart controlled, even when the value is `undefined` (shown as an
|
|
125
|
+
* empty project, e.g. while data is loading). Leave the key out entirely for uncontrolled usage.
|
|
126
|
+
*/
|
|
127
|
+
data?: ProjectInput | undefined;
|
|
128
|
+
/** Initial data for uncontrolled usage, where the engine keeps the edited data itself. */
|
|
129
|
+
defaultData?: ProjectInput | undefined;
|
|
130
|
+
onChange?: ((change: GanttDataChange) => void) | undefined;
|
|
131
|
+
/**
|
|
132
|
+
* A built-in preset id (`'hourAndDay'` … `'manyYears'`, default `'weekAndDay'`) or a custom preset. Custom
|
|
133
|
+
* presets are compared by value, but a label function is compared by identity: define custom presets outside
|
|
134
|
+
* render (or memoize them), or an inline function makes every render a change that rebuilds the time axis.
|
|
135
|
+
*/
|
|
136
|
+
preset?: string | ViewPreset | undefined;
|
|
137
|
+
/**
|
|
138
|
+
* The timeline range. Defaults to the tasks' dates with a little padding. Strings without an offset are
|
|
139
|
+
* read in the project's time zone. The timeline is always at least as wide as the viewport.
|
|
140
|
+
*/
|
|
141
|
+
startDate?: DateInput | undefined;
|
|
142
|
+
endDate?: DateInput | undefined;
|
|
143
|
+
/** Locale for header labels and cells, e.g. `'nb-NO'`. Defaults to the runtime's locale. */
|
|
144
|
+
locale?: string | undefined;
|
|
145
|
+
/** Task list columns. Defaults to name, start, end and duration. */
|
|
146
|
+
columns?: readonly ColumnInput[] | undefined;
|
|
147
|
+
/** Height of a task row in pixels. Default 44. */
|
|
148
|
+
rowHeight?: number | undefined;
|
|
149
|
+
/** Height of each header row in pixels. Default 28. */
|
|
150
|
+
headerRowHeight?: number | undefined;
|
|
151
|
+
/** Show a line at the current time. Default `true`. */
|
|
152
|
+
showToday?: boolean | undefined;
|
|
153
|
+
/**
|
|
154
|
+
* Shade non-working time from the project calendar. Default `true`. With ticks under a day, every non-working
|
|
155
|
+
* interval is shaded; with day ticks, whole non-working days; with longer ticks, nothing.
|
|
156
|
+
*/
|
|
157
|
+
showNonWorkingTime?: boolean | undefined;
|
|
158
|
+
/**
|
|
159
|
+
* Move tasks by dragging their bars. Default `true`. A drop is one change; an automatically scheduled task gets
|
|
160
|
+
* a "start no earlier than" constraint at its new start.
|
|
161
|
+
*/
|
|
162
|
+
taskDrag?: boolean | undefined;
|
|
163
|
+
/** Change a task's duration by dragging the end of its bar. Default `true`. */
|
|
164
|
+
taskResize?: boolean | undefined;
|
|
165
|
+
/** Give an unscheduled task dates by drawing its bar in its row. Default `true`. */
|
|
166
|
+
taskDragCreate?: boolean | undefined;
|
|
167
|
+
/** Change a task's percentage done by dragging the handle at its progress. Default `true`. */
|
|
168
|
+
progressDrag?: boolean | undefined;
|
|
169
|
+
/** Add dependencies by dragging from a handle at either end of a bar to another bar. Default `true`. */
|
|
170
|
+
dependencyCreate?: boolean | undefined;
|
|
171
|
+
/**
|
|
172
|
+
* Called for every change a drag proposes (move, resize, create, progress, link), while dragging and on the
|
|
173
|
+
* drop. Return `false`, or a message to show, to refuse it: the preview shows it as invalid and the drop
|
|
174
|
+
* changes nothing.
|
|
175
|
+
*/
|
|
176
|
+
validateChange?: ((change: ProposedChange) => boolean | string) | undefined;
|
|
177
|
+
/**
|
|
178
|
+
* Keep a history of changes for `undo`/`redo` (the last 100). Default `true`. Turning it off forgets the
|
|
179
|
+
* history. Controlled: a change counts once the app passes its data back; other data clears the history.
|
|
180
|
+
*/
|
|
181
|
+
undoRedo?: boolean | undefined;
|
|
182
|
+
/** Select several tasks (Ctrl/Cmd-click, Shift-click, Shift+arrows). Default `true`. */
|
|
183
|
+
multiSelect?: boolean | undefined;
|
|
184
|
+
/** Delete the selected tasks (with their subtasks) with Delete or Backspace. Default `true`. */
|
|
185
|
+
deleteKey?: boolean | undefined;
|
|
186
|
+
/** Called with the selected ids whenever the selection changes (also when deleted tasks drop out of it). */
|
|
187
|
+
onSelectionChange?: ((selection: readonly Id[]) => void) | undefined;
|
|
188
|
+
/** Show a tooltip for the task under the pointer (see `hover`). Default `true`. */
|
|
189
|
+
taskTooltip?: boolean | undefined;
|
|
190
|
+
/** Edit cells in the task list (double-click, Enter/F2). Default `true`. Each edit is one change. */
|
|
191
|
+
cellEdit?: boolean | undefined;
|
|
192
|
+
/** A context menu on tasks (right-click, the ContextMenu key or Shift+F10). Default `true`. */
|
|
193
|
+
taskMenu?: boolean | undefined;
|
|
194
|
+
/** A context menu on the time axis header, for zooming. Default `true`. */
|
|
195
|
+
timeAxisMenu?: boolean | undefined;
|
|
196
|
+
/** Change the task menu: gets the built-in items, returns the items to show. */
|
|
197
|
+
taskMenuItems?: MenuCustomizer | undefined;
|
|
198
|
+
/** Change the time axis menu: gets the built-in items, returns the items to show. */
|
|
199
|
+
timeAxisMenuItems?: MenuCustomizer | undefined;
|
|
200
|
+
/** Edit tasks in a dialog (the menu's Edit, or double-clicking a bar). Default `true`. */
|
|
201
|
+
taskEdit?: boolean | undefined;
|
|
202
|
+
/** Ids for tasks added from the menu. Defaults to unique ids like `task-12`. */
|
|
203
|
+
createTaskId?: (() => Id) | undefined;
|
|
204
|
+
/** Called with the preset's id after zooming (a zoom lasts until the `preset` option changes). */
|
|
205
|
+
onPresetChange?: ((presetId: string) => void) | undefined;
|
|
206
|
+
/**
|
|
207
|
+
* Width of the task list in pixels (its pane, border included), or `null` for automatic: as wide as the
|
|
208
|
+
* columns, up to `--qz-list-max-width`. Dragging the divider overrides it until the option changes.
|
|
209
|
+
*/
|
|
210
|
+
listWidth?: number | null | undefined;
|
|
211
|
+
/** Called after the divider changed the list's width (`null`: back to automatic, by double-clicking it). */
|
|
212
|
+
onListWidthChange?: ((width: number | null) => void) | undefined;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
// Property signatures (not methods) so the functions can be passed around unbound,
|
|
216
|
+
// e.g. `useSyncExternalStore(gantt.subscribe, gantt.getState)`.
|
|
217
|
+
export interface GanttController {
|
|
218
|
+
/** Returns the same object until the state changes, so it can back `useSyncExternalStore`. */
|
|
219
|
+
getState: () => ViewState;
|
|
220
|
+
/**
|
|
221
|
+
* The first subscription also reports (through `onChange`, after a microtask) what scheduling changed in the
|
|
222
|
+
* initial data, so the app can keep the scheduled data.
|
|
223
|
+
*/
|
|
224
|
+
subscribe: (listener: (state: ViewState) => void) => () => void;
|
|
225
|
+
/**
|
|
226
|
+
* Updates options after creation. All options are validated first: an invalid one throws and changes
|
|
227
|
+
* nothing. `data` is only honoured in controlled mode; controlled vs. uncontrolled is decided at creation.
|
|
228
|
+
*/
|
|
229
|
+
setOptions: (options: GanttOptions) => void;
|
|
230
|
+
setViewport: (viewport: Partial<Viewport>) => void;
|
|
231
|
+
/**
|
|
232
|
+
* What's under a point of the timeline body (x from the start of the axis, y from the top of the first
|
|
233
|
+
* row): a bar to move or a bar end to resize, if enabled. For the pointer cursor.
|
|
234
|
+
*/
|
|
235
|
+
hitTest: (point: TimelinePoint) => TimelineHit | null;
|
|
236
|
+
/**
|
|
237
|
+
* Pointer events on the timeline body, in the same coordinates. `pointerDown` returns whether the press
|
|
238
|
+
* counts (so the renderer can capture the pointer until `pointerUp`). Moves under 3 px are a click, which
|
|
239
|
+
* selects the row (with the modifiers held at the press); a drop is one transaction.
|
|
240
|
+
*/
|
|
241
|
+
pointerDown: (point: TimelinePoint, modifiers?: KeyModifiers) => boolean;
|
|
242
|
+
pointerMove: (point: TimelinePoint) => void;
|
|
243
|
+
pointerUp: (point: TimelinePoint) => void;
|
|
244
|
+
/** Drops the current drag without changing anything (e.g. on Escape). Returns whether there was one. */
|
|
245
|
+
cancelInteraction: () => boolean;
|
|
246
|
+
/**
|
|
247
|
+
* Changes project data. Uncontrolled: applied immediately. Controlled: only reported through
|
|
248
|
+
* `onChange`; edits in the same synchronous run build on each other, later edits build on the last
|
|
249
|
+
* `data` passed in. Returns the patch, or `null` if nothing changed.
|
|
250
|
+
*/
|
|
251
|
+
transact: (fn: (tx: Transaction) => void) => Patch | null;
|
|
252
|
+
/**
|
|
253
|
+
* Reverts the last change (exactly, scheduling included), as a change of its own: reported through
|
|
254
|
+
* `onChange`, and in controlled mode shown once the data comes back. Returns whether there was one.
|
|
255
|
+
*/
|
|
256
|
+
undo: () => boolean;
|
|
257
|
+
/** Applies the last undone change again. Returns whether there was one. */
|
|
258
|
+
redo: () => boolean;
|
|
259
|
+
/**
|
|
260
|
+
* A click on a row in the task list: selects it; Ctrl/Cmd toggles it, Shift selects the rows from the last
|
|
261
|
+
* clicked one. Unknown and hidden rows are ignored.
|
|
262
|
+
*/
|
|
263
|
+
rowClick: (id: Id, modifiers?: KeyModifiers) => void;
|
|
264
|
+
/** Selects these tasks (unknown ids are skipped); the last one gets the keyboard cursor. */
|
|
265
|
+
select: (ids: readonly Id[]) => void;
|
|
266
|
+
clearSelection: () => void;
|
|
267
|
+
/**
|
|
268
|
+
* A key pressed while the chart has focus: moves the cursor and selection, expands and collapses, deletes,
|
|
269
|
+
* undoes. Returns whether the key was used, so the renderer can stop it.
|
|
270
|
+
*/
|
|
271
|
+
keyDown: (key: KeyInput) => boolean;
|
|
272
|
+
/**
|
|
273
|
+
* The `scrollTop` that brings a visible row into view (e.g. the active one after a key press), or `null`
|
|
274
|
+
* when it's in view already, hidden or unknown.
|
|
275
|
+
*/
|
|
276
|
+
revealTop: (id: Id) => number | null;
|
|
277
|
+
/**
|
|
278
|
+
* The pointer over the timeline body (mouse or pen), for the task tooltip; `null` when it leaves. In the
|
|
279
|
+
* same coordinates as `pointerDown`.
|
|
280
|
+
*/
|
|
281
|
+
hover: (point: TimelinePoint | null) => void;
|
|
282
|
+
/**
|
|
283
|
+
* Starts editing a cell (the first editable one of the row without a column). Returns whether it can be
|
|
284
|
+
* edited; an open edit is closed either way.
|
|
285
|
+
*/
|
|
286
|
+
startEdit: (id: Id, columnId?: string) => boolean;
|
|
287
|
+
/** The text in the cell's field, as it's typed. */
|
|
288
|
+
editInput: (text: string) => void;
|
|
289
|
+
/**
|
|
290
|
+
* A key pressed in the cell's field: Enter saves, Escape cancels, Tab and Shift+Tab save and move on.
|
|
291
|
+
* Returns whether the key was used (other keys belong to the field).
|
|
292
|
+
*/
|
|
293
|
+
editKeyDown: (key: KeyInput) => boolean;
|
|
294
|
+
/** Saves the edit. Returns `false` (and keeps it open, with the reason in `error`) when it's refused. */
|
|
295
|
+
commitEdit: () => boolean;
|
|
296
|
+
cancelEdit: () => void;
|
|
297
|
+
/**
|
|
298
|
+
* Opens a context menu for a task or the time axis, at a point in the chart's coordinates (from the root
|
|
299
|
+
* element's corner); without one, at the active row. Returns whether it opened.
|
|
300
|
+
*/
|
|
301
|
+
openMenu: (target: MenuTarget, point?: { x: number; y: number }) => boolean;
|
|
302
|
+
/** A key pressed while the menu has focus. Returns whether it was used. */
|
|
303
|
+
menuKeyDown: (key: KeyInput) => boolean;
|
|
304
|
+
/** The pointer over a menu item: highlights it (and opens its submenu). */
|
|
305
|
+
menuHover: (id: string) => void;
|
|
306
|
+
/** Picks a menu item (and closes the menu). Disabled and unknown items are ignored. */
|
|
307
|
+
menuAction: (id: string) => void;
|
|
308
|
+
closeMenu: () => void;
|
|
309
|
+
/** Zooms one step (`'in'` or `'out'`) or to a built-in preset by id, keeping the middle of the view. */
|
|
310
|
+
zoom: (target: string) => boolean;
|
|
311
|
+
/** Opens the task editor. Returns whether it opened. */
|
|
312
|
+
openTaskEditor: (id: Id) => boolean;
|
|
313
|
+
/** Everything done in the task editor: typing, tabs, dependencies, saving, closing. */
|
|
314
|
+
taskEditorAction: (action: TaskEditorAction) => boolean;
|
|
315
|
+
/**
|
|
316
|
+
* The divider between the task list and the timeline: drag it (start, move, end or cancel), move it with keys
|
|
317
|
+
* (arrows, with Shift for bigger steps, Home and End), or reset it to automatic. Returns whether it was used.
|
|
318
|
+
*/
|
|
319
|
+
resizeList: (action: ListResizeAction) => boolean;
|
|
320
|
+
/** A double-click on the timeline body: opens the editor for the bar there. Returns whether it did. */
|
|
321
|
+
doubleClick: (point: TimelinePoint) => boolean;
|
|
322
|
+
/** Expands a collapsed task or collapses an expanded one. Unknown ids and leaf tasks are ignored. */
|
|
323
|
+
toggle: (id: Id) => void;
|
|
324
|
+
setExpanded: (id: Id, expanded: boolean) => void;
|
|
325
|
+
expandAll: () => void;
|
|
326
|
+
collapseAll: () => void;
|
|
327
|
+
destroy: () => void;
|
|
328
|
+
}
|