@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,120 @@
|
|
|
1
|
+
import { MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND } from '../util/civil';
|
|
2
|
+
import type { TimeUnit } from '../util/time';
|
|
3
|
+
import {
|
|
4
|
+
addUnits,
|
|
5
|
+
fromWallTime,
|
|
6
|
+
startOfUnit,
|
|
7
|
+
toWallTime,
|
|
8
|
+
wallDay,
|
|
9
|
+
zoneOffset,
|
|
10
|
+
type TimeZone,
|
|
11
|
+
} from '../util/zone';
|
|
12
|
+
|
|
13
|
+
const mod = (value: number, divisor: number): number => ((value % divisor) + divisor) % divisor;
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Start of the `increment`-sized unit containing `time`, aligned to natural boundaries: 6 hours → 00, 06,
|
|
17
|
+
* 12, 18; 3 months → January, April, …; 5 years → 2025, 2030, …
|
|
18
|
+
*/
|
|
19
|
+
export function alignToUnit(
|
|
20
|
+
time: number,
|
|
21
|
+
unit: TimeUnit,
|
|
22
|
+
increment: number,
|
|
23
|
+
zone: TimeZone,
|
|
24
|
+
weekStartsOn: number,
|
|
25
|
+
): number {
|
|
26
|
+
const base = startOfUnit(time, unit, zone, weekStartsOn);
|
|
27
|
+
if (increment === 1) return base;
|
|
28
|
+
|
|
29
|
+
const wall = toWallTime(base, zone);
|
|
30
|
+
let position: number;
|
|
31
|
+
switch (unit) {
|
|
32
|
+
case 'millisecond':
|
|
33
|
+
position = wall.millisecond;
|
|
34
|
+
break;
|
|
35
|
+
case 'second':
|
|
36
|
+
position = wall.second;
|
|
37
|
+
break;
|
|
38
|
+
case 'minute':
|
|
39
|
+
position = wall.minute;
|
|
40
|
+
break;
|
|
41
|
+
case 'hour':
|
|
42
|
+
position = wall.hour;
|
|
43
|
+
break;
|
|
44
|
+
case 'day':
|
|
45
|
+
position = wallDay(base, zone);
|
|
46
|
+
break;
|
|
47
|
+
case 'week':
|
|
48
|
+
// Every week start is the same weekday, so this counts weeks consistently.
|
|
49
|
+
position = Math.floor(wallDay(base, zone) / 7);
|
|
50
|
+
break;
|
|
51
|
+
case 'month':
|
|
52
|
+
position = wall.month - 1;
|
|
53
|
+
break;
|
|
54
|
+
case 'quarter':
|
|
55
|
+
position = Math.floor((wall.month - 1) / 3);
|
|
56
|
+
break;
|
|
57
|
+
case 'year':
|
|
58
|
+
position = wall.year;
|
|
59
|
+
break;
|
|
60
|
+
}
|
|
61
|
+
const remainder = mod(position, increment);
|
|
62
|
+
if (remainder === 0) return base;
|
|
63
|
+
switch (unit) {
|
|
64
|
+
// Sub-day units: go back on the wall clock, not by a fixed duration, which would overshoot across a
|
|
65
|
+
// DST gap (03:00 on spring-forward day minus 3 hours is 23:00 the day before, not 00:00).
|
|
66
|
+
case 'millisecond':
|
|
67
|
+
return fromWallTime({ ...wall, millisecond: wall.millisecond - remainder }, zone);
|
|
68
|
+
case 'second':
|
|
69
|
+
return fromWallTime({ ...wall, second: wall.second - remainder }, zone);
|
|
70
|
+
case 'minute':
|
|
71
|
+
return fromWallTime({ ...wall, minute: wall.minute - remainder }, zone);
|
|
72
|
+
case 'hour':
|
|
73
|
+
return fromWallTime({ ...wall, hour: wall.hour - remainder }, zone);
|
|
74
|
+
default:
|
|
75
|
+
return addUnits(base, -remainder, unit, zone);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const SUB_DAY_SIZE: Partial<Record<TimeUnit, number>> = {
|
|
80
|
+
millisecond: 1,
|
|
81
|
+
second: MS_PER_SECOND,
|
|
82
|
+
minute: MS_PER_MINUTE,
|
|
83
|
+
hour: MS_PER_HOUR,
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* The natural boundary after an aligned boundary. Always re-aligns instead of adding a fixed step, so the
|
|
88
|
+
* result doesn't depend on where counting started.
|
|
89
|
+
*/
|
|
90
|
+
export function nextBoundary(
|
|
91
|
+
boundary: number,
|
|
92
|
+
unit: TimeUnit,
|
|
93
|
+
increment: number,
|
|
94
|
+
zone: TimeZone,
|
|
95
|
+
weekStartsOn: number,
|
|
96
|
+
): number {
|
|
97
|
+
// Fast path: if `boundary` sits exactly on a wall-clock boundary (not shifted by a DST gap) and the UTC
|
|
98
|
+
// offset is the same one step later, the wall clock moved exactly one step, so a fixed step lands on the
|
|
99
|
+
// next natural boundary. This is the common case (no DST change in between) and avoids wall-clock math.
|
|
100
|
+
const subDay = SUB_DAY_SIZE[unit];
|
|
101
|
+
const step = subDay ?? (unit === 'day' ? MS_PER_DAY : unit === 'week' ? 7 * MS_PER_DAY : undefined);
|
|
102
|
+
if (step !== undefined) {
|
|
103
|
+
const offset = zoneOffset(boundary, zone);
|
|
104
|
+
const candidate = boundary + step * increment;
|
|
105
|
+
if (mod(boundary + offset, subDay ?? MS_PER_DAY) === 0 && zoneOffset(candidate, zone) === offset) {
|
|
106
|
+
return candidate;
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
const size = SUB_DAY_SIZE[unit];
|
|
111
|
+
if (size !== undefined) {
|
|
112
|
+
// Step half a step past the next boundary, then align down. A plain 6-hour step would drift from
|
|
113
|
+
// 00/06/12/18 to 07/13/19 after a DST change.
|
|
114
|
+
const next = alignToUnit(boundary + size * increment * 1.5, unit, increment, zone, weekStartsOn);
|
|
115
|
+
return next > boundary ? next : boundary + size * increment;
|
|
116
|
+
}
|
|
117
|
+
// Days and longer: step on the wall calendar and re-align, so a DST change that skips midnight
|
|
118
|
+
// (e.g. Cairo) doesn't leave every later boundary at 01:00.
|
|
119
|
+
return alignToUnit(addUnits(boundary, increment, unit, zone), unit, increment, zone, weekStartsOn);
|
|
120
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { QuartzioError } from '../util/errors';
|
|
2
|
+
import { isoWeek, toWallTime } from '../util/zone';
|
|
3
|
+
import type { HeaderCellContext, HeaderFormat, HeaderFormatName } from './presets';
|
|
4
|
+
|
|
5
|
+
const INTL_OPTIONS: Partial<Record<HeaderFormatName, Intl.DateTimeFormatOptions>> = {
|
|
6
|
+
year: { year: 'numeric' },
|
|
7
|
+
month: { month: 'long' },
|
|
8
|
+
monthShort: { month: 'short' },
|
|
9
|
+
monthYear: { month: 'long', year: 'numeric' },
|
|
10
|
+
monthShortYear: { month: 'short', year: 'numeric' },
|
|
11
|
+
day: { day: 'numeric' },
|
|
12
|
+
weekdayShort: { weekday: 'short' },
|
|
13
|
+
weekdayNarrow: { weekday: 'narrow' },
|
|
14
|
+
weekdayDay: { weekday: 'short', day: 'numeric' },
|
|
15
|
+
dayMonth: { day: 'numeric', month: 'short' },
|
|
16
|
+
weekdayDayMonth: { weekday: 'short', day: 'numeric', month: 'short' },
|
|
17
|
+
hour: { hour: 'numeric' },
|
|
18
|
+
hourMinute: { hour: '2-digit', minute: '2-digit' },
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
const formatters = new Map<string, Intl.DateTimeFormat>();
|
|
22
|
+
|
|
23
|
+
function formatterFor(name: HeaderFormatName, cell: HeaderCellContext): Intl.DateTimeFormat {
|
|
24
|
+
const key = `${name}|${cell.locale ?? ''}|${cell.timeZone}`;
|
|
25
|
+
let formatter = formatters.get(key);
|
|
26
|
+
if (!formatter) {
|
|
27
|
+
const options = INTL_OPTIONS[name] ?? {};
|
|
28
|
+
formatter = new Intl.DateTimeFormat(
|
|
29
|
+
cell.locale,
|
|
30
|
+
cell.timeZone === 'local' ? options : { ...options, timeZone: cell.timeZone },
|
|
31
|
+
);
|
|
32
|
+
formatters.set(key, formatter);
|
|
33
|
+
}
|
|
34
|
+
return formatter;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Throws QuartzioError for malformed locale tags (unsupported but well-formed tags fall back silently). */
|
|
38
|
+
export function assertLocale(locale: unknown): void {
|
|
39
|
+
try {
|
|
40
|
+
if (typeof locale !== 'string') throw new TypeError();
|
|
41
|
+
Intl.DateTimeFormat.supportedLocalesOf(locale);
|
|
42
|
+
} catch {
|
|
43
|
+
throw new QuartzioError(
|
|
44
|
+
`"${String(locale)}" is not a valid locale. Use a BCP 47 tag such as "en-US" or "nb-NO".`,
|
|
45
|
+
);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export function formatHeaderCell(format: HeaderFormat, cell: HeaderCellContext): string {
|
|
50
|
+
if (typeof format === 'function') {
|
|
51
|
+
// A bug in a custom label must not break rendering (or leave the controller in a broken state).
|
|
52
|
+
try {
|
|
53
|
+
const label: unknown = format(cell);
|
|
54
|
+
return typeof label === 'string' ? label : String(label);
|
|
55
|
+
} catch {
|
|
56
|
+
return '';
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
switch (format) {
|
|
60
|
+
case 'quarter':
|
|
61
|
+
case 'quarterYear': {
|
|
62
|
+
const { year, month } = toWallTime(cell.start, cell.timeZone);
|
|
63
|
+
const quarter = `Q${String(Math.floor((month - 1) / 3) + 1)}`;
|
|
64
|
+
return format === 'quarter' ? quarter : `${quarter} ${String(year)}`;
|
|
65
|
+
}
|
|
66
|
+
case 'week':
|
|
67
|
+
// The middle of the cell, so weeks starting on Sunday still get the ISO number of their Mon–Sat.
|
|
68
|
+
return `W${String(isoWeek(cell.start + (cell.end - cell.start) / 2, cell.timeZone).week)}`;
|
|
69
|
+
default:
|
|
70
|
+
return formatterFor(format, cell).format(cell.start);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
import { deepFreeze } from '../util/equal';
|
|
2
|
+
import { QuartzioError } from '../util/errors';
|
|
3
|
+
import { isTimeUnit, type TimeUnit } from '../util/time';
|
|
4
|
+
import type { TimeZone } from '../util/zone';
|
|
5
|
+
|
|
6
|
+
export interface HeaderCellContext {
|
|
7
|
+
start: number;
|
|
8
|
+
end: number;
|
|
9
|
+
unit: TimeUnit;
|
|
10
|
+
increment: number;
|
|
11
|
+
timeZone: TimeZone;
|
|
12
|
+
/** BCP 47 locale, e.g. "nb-NO"; `undefined` uses the runtime default. */
|
|
13
|
+
locale: string | undefined;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** Built-in label formats. Month and weekday names follow the locale. */
|
|
17
|
+
export type HeaderFormatName =
|
|
18
|
+
| 'year'
|
|
19
|
+
| 'quarter'
|
|
20
|
+
| 'quarterYear'
|
|
21
|
+
| 'month'
|
|
22
|
+
| 'monthShort'
|
|
23
|
+
| 'monthYear'
|
|
24
|
+
| 'monthShortYear'
|
|
25
|
+
/** ISO 8601 week number, e.g. "W41". */
|
|
26
|
+
| 'week'
|
|
27
|
+
| 'day'
|
|
28
|
+
| 'weekdayShort'
|
|
29
|
+
| 'weekdayNarrow'
|
|
30
|
+
| 'weekdayDay'
|
|
31
|
+
| 'dayMonth'
|
|
32
|
+
| 'weekdayDayMonth'
|
|
33
|
+
| 'hour'
|
|
34
|
+
| 'hourMinute';
|
|
35
|
+
|
|
36
|
+
/** A built-in format, or a function. Functions should be pure and must not throw (errors leave the label empty). */
|
|
37
|
+
export type HeaderFormat = HeaderFormatName | ((cell: HeaderCellContext) => string);
|
|
38
|
+
|
|
39
|
+
export const HEADER_FORMATS: readonly HeaderFormatName[] = [
|
|
40
|
+
'year',
|
|
41
|
+
'quarter',
|
|
42
|
+
'quarterYear',
|
|
43
|
+
'month',
|
|
44
|
+
'monthShort',
|
|
45
|
+
'monthYear',
|
|
46
|
+
'monthShortYear',
|
|
47
|
+
'week',
|
|
48
|
+
'day',
|
|
49
|
+
'weekdayShort',
|
|
50
|
+
'weekdayNarrow',
|
|
51
|
+
'weekdayDay',
|
|
52
|
+
'dayMonth',
|
|
53
|
+
'weekdayDayMonth',
|
|
54
|
+
'hour',
|
|
55
|
+
'hourMinute',
|
|
56
|
+
];
|
|
57
|
+
|
|
58
|
+
export interface HeaderRow {
|
|
59
|
+
unit: TimeUnit;
|
|
60
|
+
/** Units per cell. Defaults to 1. */
|
|
61
|
+
increment?: number;
|
|
62
|
+
format: HeaderFormat;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export interface ViewPreset {
|
|
66
|
+
id: string;
|
|
67
|
+
/** The smallest column. Every tick gets the same width, however long it is in time. */
|
|
68
|
+
tickUnit: TimeUnit;
|
|
69
|
+
tickIncrement: number;
|
|
70
|
+
/** Pixels per tick. */
|
|
71
|
+
tickWidth: number;
|
|
72
|
+
/** Header rows from top to bottom. */
|
|
73
|
+
headers: readonly HeaderRow[];
|
|
74
|
+
/** Resolution for snapping when dragging and resizing. */
|
|
75
|
+
timeResolution: { unit: TimeUnit; increment: number };
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Built-in presets, from most zoomed in to most zoomed out. */
|
|
79
|
+
export const VIEW_PRESETS: readonly ViewPreset[] = deepFreeze([
|
|
80
|
+
{
|
|
81
|
+
id: 'hourAndDay',
|
|
82
|
+
tickUnit: 'hour',
|
|
83
|
+
tickIncrement: 1,
|
|
84
|
+
tickWidth: 44,
|
|
85
|
+
headers: [
|
|
86
|
+
{ unit: 'day', format: 'weekdayDayMonth' },
|
|
87
|
+
{ unit: 'hour', format: 'hour' },
|
|
88
|
+
],
|
|
89
|
+
timeResolution: { unit: 'minute', increment: 15 },
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
id: 'dayAndWeek',
|
|
93
|
+
tickUnit: 'day',
|
|
94
|
+
tickIncrement: 1,
|
|
95
|
+
tickWidth: 64,
|
|
96
|
+
headers: [
|
|
97
|
+
{ unit: 'week', format: 'week' },
|
|
98
|
+
{ unit: 'day', format: 'weekdayDay' },
|
|
99
|
+
],
|
|
100
|
+
timeResolution: { unit: 'hour', increment: 1 },
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
id: 'weekAndDay',
|
|
104
|
+
tickUnit: 'day',
|
|
105
|
+
tickIncrement: 1,
|
|
106
|
+
tickWidth: 32,
|
|
107
|
+
headers: [
|
|
108
|
+
{ unit: 'month', format: 'monthYear' },
|
|
109
|
+
{ unit: 'week', format: 'week' },
|
|
110
|
+
{ unit: 'day', format: 'weekdayNarrow' },
|
|
111
|
+
],
|
|
112
|
+
timeResolution: { unit: 'day', increment: 1 },
|
|
113
|
+
},
|
|
114
|
+
{
|
|
115
|
+
id: 'weekAndMonth',
|
|
116
|
+
tickUnit: 'week',
|
|
117
|
+
tickIncrement: 1,
|
|
118
|
+
tickWidth: 56,
|
|
119
|
+
headers: [
|
|
120
|
+
{ unit: 'month', format: 'monthShortYear' },
|
|
121
|
+
{ unit: 'week', format: 'week' },
|
|
122
|
+
],
|
|
123
|
+
timeResolution: { unit: 'day', increment: 1 },
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
id: 'monthAndYear',
|
|
127
|
+
tickUnit: 'month',
|
|
128
|
+
tickIncrement: 1,
|
|
129
|
+
tickWidth: 72,
|
|
130
|
+
headers: [
|
|
131
|
+
{ unit: 'year', format: 'year' },
|
|
132
|
+
{ unit: 'month', format: 'monthShort' },
|
|
133
|
+
],
|
|
134
|
+
timeResolution: { unit: 'day', increment: 1 },
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
id: 'quarterAndYear',
|
|
138
|
+
tickUnit: 'quarter',
|
|
139
|
+
tickIncrement: 1,
|
|
140
|
+
tickWidth: 96,
|
|
141
|
+
headers: [
|
|
142
|
+
{ unit: 'year', format: 'year' },
|
|
143
|
+
{ unit: 'quarter', format: 'quarter' },
|
|
144
|
+
],
|
|
145
|
+
timeResolution: { unit: 'week', increment: 1 },
|
|
146
|
+
},
|
|
147
|
+
{
|
|
148
|
+
id: 'manyYears',
|
|
149
|
+
tickUnit: 'year',
|
|
150
|
+
tickIncrement: 1,
|
|
151
|
+
tickWidth: 72,
|
|
152
|
+
headers: [
|
|
153
|
+
{ unit: 'year', increment: 5, format: 'year' },
|
|
154
|
+
{ unit: 'year', format: 'year' },
|
|
155
|
+
],
|
|
156
|
+
timeResolution: { unit: 'month', increment: 1 },
|
|
157
|
+
},
|
|
158
|
+
]);
|
|
159
|
+
|
|
160
|
+
export const DEFAULT_PRESET_ID = 'weekAndDay';
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* Increments must divide the next larger unit evenly (6 hours, not 5), so cells and ticks line up with
|
|
164
|
+
* natural boundaries wherever you start counting. Days, weeks and years can use any whole number.
|
|
165
|
+
*/
|
|
166
|
+
const ALLOWED_INCREMENTS: Partial<Record<TimeUnit, readonly number[]>> = {
|
|
167
|
+
millisecond: [1, 2, 4, 5, 8, 10, 20, 25, 40, 50, 100, 125, 200, 250, 500],
|
|
168
|
+
second: [1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30],
|
|
169
|
+
minute: [1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30],
|
|
170
|
+
hour: [1, 2, 3, 4, 6, 8, 12],
|
|
171
|
+
month: [1, 2, 3, 4, 6],
|
|
172
|
+
quarter: [1, 2],
|
|
173
|
+
};
|
|
174
|
+
|
|
175
|
+
function assertUnitAndIncrement(unit: unknown, increment: unknown, owner: string): void {
|
|
176
|
+
if (!isTimeUnit(unit)) throw new QuartzioError(`${owner}: "${String(unit)}" is not a time unit.`);
|
|
177
|
+
if (typeof increment !== 'number' || !Number.isInteger(increment) || increment < 1) {
|
|
178
|
+
throw new QuartzioError(`${owner}: increment must be a whole number >= 1.`);
|
|
179
|
+
}
|
|
180
|
+
const allowed = ALLOWED_INCREMENTS[unit];
|
|
181
|
+
if (allowed && !allowed.includes(increment)) {
|
|
182
|
+
throw new QuartzioError(`${owner}: a "${unit}" increment must be one of ${allowed.join(', ')}.`);
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** Looks up a built-in preset by id, or validates a custom one. */
|
|
187
|
+
export function resolvePreset(preset: string | ViewPreset = DEFAULT_PRESET_ID): ViewPreset {
|
|
188
|
+
if (typeof preset === 'string') {
|
|
189
|
+
const found = VIEW_PRESETS.find((candidate) => candidate.id === preset);
|
|
190
|
+
if (!found) {
|
|
191
|
+
throw new QuartzioError(
|
|
192
|
+
`Unknown view preset "${preset}". Built-in presets: ${VIEW_PRESETS.map((p) => p.id).join(', ')}.`,
|
|
193
|
+
);
|
|
194
|
+
}
|
|
195
|
+
return found;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
const owner = `View preset "${String((preset as Partial<ViewPreset> | null)?.id)}"`;
|
|
199
|
+
if (typeof preset !== 'object' || typeof preset.id !== 'string' || preset.id === '') {
|
|
200
|
+
throw new QuartzioError('A view preset needs a non-empty string id.');
|
|
201
|
+
}
|
|
202
|
+
if (typeof preset.tickWidth !== 'number' || !Number.isFinite(preset.tickWidth) || preset.tickWidth <= 0) {
|
|
203
|
+
throw new QuartzioError(`${owner}: tickWidth must be a number above 0.`);
|
|
204
|
+
}
|
|
205
|
+
assertUnitAndIncrement(preset.tickUnit, preset.tickIncrement, `${owner} (ticks)`);
|
|
206
|
+
const resolution = preset.timeResolution as ViewPreset['timeResolution'] | undefined;
|
|
207
|
+
assertUnitAndIncrement(resolution?.unit, resolution?.increment, `${owner} (timeResolution)`);
|
|
208
|
+
if (!Array.isArray(preset.headers) || preset.headers.length === 0) {
|
|
209
|
+
throw new QuartzioError(`${owner}: headers must be a non-empty array.`);
|
|
210
|
+
}
|
|
211
|
+
preset.headers.forEach((row: HeaderRow, index) => {
|
|
212
|
+
const rowOwner = `${owner} (header row ${String(index)})`;
|
|
213
|
+
assertUnitAndIncrement(row.unit, row.increment ?? 1, rowOwner);
|
|
214
|
+
if (typeof row.format !== 'function' && !HEADER_FORMATS.includes(row.format)) {
|
|
215
|
+
throw new QuartzioError(`${rowOwner}: unknown format "${row.format}".`);
|
|
216
|
+
}
|
|
217
|
+
});
|
|
218
|
+
return preset;
|
|
219
|
+
}
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
import { QuartzioError } from '../util/errors';
|
|
2
|
+
import type { TimeZone } from '../util/zone';
|
|
3
|
+
import { alignToUnit, nextBoundary } from './align';
|
|
4
|
+
import { formatHeaderCell } from './format';
|
|
5
|
+
import type { ViewPreset } from './presets';
|
|
6
|
+
|
|
7
|
+
export interface TimeAxisOptions {
|
|
8
|
+
/** The axis is widened to whole ticks around `[start, end)`. */
|
|
9
|
+
start: number;
|
|
10
|
+
end: number;
|
|
11
|
+
preset: ViewPreset;
|
|
12
|
+
timeZone: TimeZone;
|
|
13
|
+
/** 0 = Sunday … 6 = Saturday. */
|
|
14
|
+
weekStartsOn: number;
|
|
15
|
+
locale?: string | undefined;
|
|
16
|
+
/** Adds ticks after `end` until the axis is at least this many pixels wide (e.g. to fill a viewport). */
|
|
17
|
+
minWidth?: number | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* When the range needs more than `MAX_TICKS` ticks: stop there (the axis ends early) instead of
|
|
20
|
+
* throwing. Used by the controller, which must never fail while rendering.
|
|
21
|
+
*/
|
|
22
|
+
truncate?: boolean | undefined;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export interface Tick {
|
|
26
|
+
index: number;
|
|
27
|
+
start: number;
|
|
28
|
+
end: number;
|
|
29
|
+
x: number;
|
|
30
|
+
width: number;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface HeaderCell {
|
|
34
|
+
/** Stable key for rendering lists. */
|
|
35
|
+
key: string;
|
|
36
|
+
/** The cell's full time span; it may extend beyond the axis at the edges. */
|
|
37
|
+
start: number;
|
|
38
|
+
end: number;
|
|
39
|
+
/** Position and width, clipped to the axis. */
|
|
40
|
+
x: number;
|
|
41
|
+
width: number;
|
|
42
|
+
label: string;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Maps time to pixels and back. Every tick has the same width; within a tick, position is linear in
|
|
47
|
+
* time. So a 23-hour DST day is as wide as any other day, and every month is as wide as every other.
|
|
48
|
+
*/
|
|
49
|
+
export interface TimeAxis {
|
|
50
|
+
readonly preset: ViewPreset;
|
|
51
|
+
readonly timeZone: TimeZone;
|
|
52
|
+
readonly locale: string | undefined;
|
|
53
|
+
readonly weekStartsOn: number;
|
|
54
|
+
/** First tick start and last tick end. */
|
|
55
|
+
readonly start: number;
|
|
56
|
+
readonly end: number;
|
|
57
|
+
readonly tickCount: number;
|
|
58
|
+
readonly tickWidth: number;
|
|
59
|
+
readonly totalWidth: number;
|
|
60
|
+
tick: (index: number) => Tick;
|
|
61
|
+
/** Pixel position of a time. Times outside the axis are extrapolated from the edge ticks. */
|
|
62
|
+
dateToX: (time: number) => number;
|
|
63
|
+
/** Time at a pixel position; the inverse of `dateToX`, rounded to whole milliseconds. */
|
|
64
|
+
xToDate: (x: number) => number;
|
|
65
|
+
/** Ticks overlapping `[fromX, toX)`. */
|
|
66
|
+
ticksInRange: (fromX: number, toX: number) => Tick[];
|
|
67
|
+
/**
|
|
68
|
+
* Cells of header row `row` (0 = top) overlapping `[fromX, toX)`, clipped to the axis. Always aligned to
|
|
69
|
+
* natural boundaries, so the same cells come back whatever window is asked for. At most 10 000 cells.
|
|
70
|
+
*/
|
|
71
|
+
headerCells: (row: number, fromX: number, toX: number) => HeaderCell[];
|
|
72
|
+
/** Rounds to the nearest `timeResolution` boundary of the preset. */
|
|
73
|
+
snap: (time: number) => number;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** Guards against presets that would create absurd numbers of ticks (e.g. hours over centuries). */
|
|
77
|
+
export const MAX_TICKS = 200_000;
|
|
78
|
+
const MAX_HEADER_CELLS = 10_000;
|
|
79
|
+
|
|
80
|
+
export function createTimeAxis(options: TimeAxisOptions): TimeAxis {
|
|
81
|
+
const { preset, timeZone, weekStartsOn, locale } = options;
|
|
82
|
+
const { tickUnit, tickIncrement, tickWidth } = preset;
|
|
83
|
+
if (!Number.isFinite(options.start) || !Number.isFinite(options.end)) {
|
|
84
|
+
throw new QuartzioError('Time axis: start and end must be finite times.');
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
const minTicks = Math.ceil((options.minWidth ?? 0) / tickWidth);
|
|
88
|
+
const boundaries: number[] = [alignToUnit(options.start, tickUnit, tickIncrement, timeZone, weekStartsOn)];
|
|
89
|
+
do {
|
|
90
|
+
if (boundaries.length - 1 >= MAX_TICKS) {
|
|
91
|
+
if (options.truncate) break;
|
|
92
|
+
throw new QuartzioError(
|
|
93
|
+
`Time axis: more than ${String(MAX_TICKS)} ticks. Use a more zoomed-out preset or a shorter range.`,
|
|
94
|
+
);
|
|
95
|
+
}
|
|
96
|
+
const last = boundaries[boundaries.length - 1] as number;
|
|
97
|
+
boundaries.push(nextBoundary(last, tickUnit, tickIncrement, timeZone, weekStartsOn));
|
|
98
|
+
} while ((boundaries[boundaries.length - 1] as number) < options.end || boundaries.length - 1 < minTicks);
|
|
99
|
+
|
|
100
|
+
const tickCount = boundaries.length - 1;
|
|
101
|
+
const totalWidth = tickCount * tickWidth;
|
|
102
|
+
const boundary = (i: number): number => boundaries[i] as number;
|
|
103
|
+
const start = boundary(0);
|
|
104
|
+
const end = boundary(tickCount);
|
|
105
|
+
|
|
106
|
+
/** Index of the tick containing `time` (which must be inside the axis). */
|
|
107
|
+
const tickIndexAt = (time: number): number => {
|
|
108
|
+
let low = 0;
|
|
109
|
+
let high = tickCount - 1;
|
|
110
|
+
while (low < high) {
|
|
111
|
+
const middle = (low + high + 1) >> 1;
|
|
112
|
+
if (boundary(middle) <= time) low = middle;
|
|
113
|
+
else high = middle - 1;
|
|
114
|
+
}
|
|
115
|
+
return low;
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
const tick = (index: number): Tick => ({
|
|
119
|
+
index,
|
|
120
|
+
start: boundary(index),
|
|
121
|
+
end: boundary(index + 1),
|
|
122
|
+
x: index * tickWidth,
|
|
123
|
+
width: tickWidth,
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
const dateToX = (time: number): number => {
|
|
127
|
+
if (time < start) return ((time - start) / (boundary(1) - start)) * tickWidth;
|
|
128
|
+
if (time >= end) return totalWidth + ((time - end) / (end - boundary(tickCount - 1))) * tickWidth;
|
|
129
|
+
const i = tickIndexAt(time);
|
|
130
|
+
return i * tickWidth + ((time - boundary(i)) / (boundary(i + 1) - boundary(i))) * tickWidth;
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
const xToDate = (x: number): number => {
|
|
134
|
+
const i = Math.floor(x / tickWidth);
|
|
135
|
+
if (i < 0) return Math.round(start + (x / tickWidth) * (boundary(1) - start));
|
|
136
|
+
if (i >= tickCount) {
|
|
137
|
+
return Math.round(end + ((x - totalWidth) / tickWidth) * (end - boundary(tickCount - 1)));
|
|
138
|
+
}
|
|
139
|
+
return Math.round(boundary(i) + ((x - i * tickWidth) / tickWidth) * (boundary(i + 1) - boundary(i)));
|
|
140
|
+
};
|
|
141
|
+
|
|
142
|
+
const clampIndex = (i: number): number => Math.max(0, Math.min(tickCount, i));
|
|
143
|
+
|
|
144
|
+
return {
|
|
145
|
+
preset,
|
|
146
|
+
timeZone,
|
|
147
|
+
locale,
|
|
148
|
+
weekStartsOn,
|
|
149
|
+
start,
|
|
150
|
+
end,
|
|
151
|
+
tickCount,
|
|
152
|
+
tickWidth,
|
|
153
|
+
totalWidth,
|
|
154
|
+
tick,
|
|
155
|
+
dateToX,
|
|
156
|
+
xToDate,
|
|
157
|
+
|
|
158
|
+
ticksInRange(fromX, toX) {
|
|
159
|
+
const first = clampIndex(Math.floor(fromX / tickWidth));
|
|
160
|
+
const last = clampIndex(Math.ceil(toX / tickWidth));
|
|
161
|
+
const result: Tick[] = [];
|
|
162
|
+
for (let i = first; i < last; i++) result.push(tick(i));
|
|
163
|
+
return result;
|
|
164
|
+
},
|
|
165
|
+
|
|
166
|
+
headerCells(row, fromX, toX) {
|
|
167
|
+
const header = preset.headers[row];
|
|
168
|
+
if (!header)
|
|
169
|
+
throw new QuartzioError(`Time axis: preset "${preset.id}" has no header row ${String(row)}.`);
|
|
170
|
+
const increment = header.increment ?? 1;
|
|
171
|
+
const from = Math.max(start, xToDate(fromX));
|
|
172
|
+
const to = Math.min(end, xToDate(toX));
|
|
173
|
+
const cells: HeaderCell[] = [];
|
|
174
|
+
let cellStart = alignToUnit(from, header.unit, increment, timeZone, weekStartsOn);
|
|
175
|
+
while (cellStart < to && cells.length < MAX_HEADER_CELLS) {
|
|
176
|
+
const cellEnd = nextBoundary(cellStart, header.unit, increment, timeZone, weekStartsOn);
|
|
177
|
+
const x = dateToX(Math.max(cellStart, start));
|
|
178
|
+
cells.push({
|
|
179
|
+
key: `${String(row)}:${String(cellStart)}`,
|
|
180
|
+
start: cellStart,
|
|
181
|
+
end: cellEnd,
|
|
182
|
+
x,
|
|
183
|
+
width: dateToX(Math.min(cellEnd, end)) - x,
|
|
184
|
+
label: formatHeaderCell(header.format, {
|
|
185
|
+
start: cellStart,
|
|
186
|
+
end: cellEnd,
|
|
187
|
+
unit: header.unit,
|
|
188
|
+
increment,
|
|
189
|
+
timeZone,
|
|
190
|
+
locale,
|
|
191
|
+
}),
|
|
192
|
+
});
|
|
193
|
+
cellStart = cellEnd;
|
|
194
|
+
}
|
|
195
|
+
return cells;
|
|
196
|
+
},
|
|
197
|
+
|
|
198
|
+
snap(time) {
|
|
199
|
+
const { unit, increment } = preset.timeResolution;
|
|
200
|
+
const floor = alignToUnit(time, unit, increment, timeZone, weekStartsOn);
|
|
201
|
+
const ceil = nextBoundary(floor, unit, increment, timeZone, weekStartsOn);
|
|
202
|
+
return time - floor < ceil - time ? floor : ceil;
|
|
203
|
+
},
|
|
204
|
+
};
|
|
205
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// Calendar-date ("civil") arithmetic, independent of any time zone. A civil day number counts days
|
|
2
|
+
// since 1970-01-01; it names a date on the wall calendar, not an instant.
|
|
3
|
+
|
|
4
|
+
export const MS_PER_SECOND = 1000;
|
|
5
|
+
export const MS_PER_MINUTE: number = 60 * MS_PER_SECOND;
|
|
6
|
+
export const MS_PER_HOUR: number = 60 * MS_PER_MINUTE;
|
|
7
|
+
export const MS_PER_DAY: number = 24 * MS_PER_HOUR;
|
|
8
|
+
|
|
9
|
+
export interface CivilDate {
|
|
10
|
+
year: number;
|
|
11
|
+
/** 1–12 */
|
|
12
|
+
month: number;
|
|
13
|
+
/** 1–31 */
|
|
14
|
+
day: number;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** Day number for a date. Out-of-range months and days roll over (month 13 → January next year). */
|
|
18
|
+
export function daysFromCivil(year: number, month: number, day: number): number {
|
|
19
|
+
const date = new Date(0);
|
|
20
|
+
// setUTCFullYear, not Date.UTC: Date.UTC maps years 0–99 to 1900–1999.
|
|
21
|
+
date.setUTCFullYear(year, month - 1, day);
|
|
22
|
+
return Math.round(date.getTime() / MS_PER_DAY);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export function civilFromDays(days: number): CivilDate {
|
|
26
|
+
const date = new Date(days * MS_PER_DAY);
|
|
27
|
+
return { year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate() };
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** 0 = Sunday … 6 = Saturday. */
|
|
31
|
+
export function weekdayFromDays(days: number): number {
|
|
32
|
+
// 1970-01-01 was a Thursday.
|
|
33
|
+
return (((days + 4) % 7) + 7) % 7;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export function daysInMonth(year: number, month: number): number {
|
|
37
|
+
return daysFromCivil(year, month + 1, 1) - daysFromCivil(year, month, 1);
|
|
38
|
+
}
|