@wtfalch/calendar 0.1.0 → 0.3.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/README.md +4 -0
- package/dist/calendar/calendar-client.js +574 -19
- package/dist/calendar/calendar.css +13 -0
- package/dist/calendar/client.d.ts +27 -0
- package/dist/calendar/client.js +101 -0
- package/dist/calendar/fake/sample.d.ts +2 -1
- package/dist/calendar/fake/store.d.ts +51 -8
- package/dist/calendar/fake/store.js +539 -47
- package/dist/calendar/find-time.d.ts +17 -0
- package/dist/calendar/find-time.js +198 -0
- package/dist/calendar/ics.d.ts +73 -0
- package/dist/calendar/ics.js +586 -0
- package/dist/calendar/index.d.ts +3 -1
- package/dist/calendar/index.js +1 -0
- package/dist/calendar/react/Calendar.js +36 -27
- package/dist/calendar/react/EventDetail.js +22 -1
- package/dist/calendar/react/EventEditor.js +65 -3
- package/dist/calendar/types.d.ts +550 -17
- package/dist/calendar/wire.d.ts +161 -5
- package/dist/calendar/wire.js +304 -4
- package/package.json +2 -2
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The pure slot search behind `CalendarClient.findTime` (issue #13). No
|
|
3
|
+
* network and no server-shaped types here — just merging busy periods and
|
|
4
|
+
* walking the gaps between them, so the search itself is testable without a
|
|
5
|
+
* connection at all.
|
|
6
|
+
*/
|
|
7
|
+
import type { AvailabilityResult, CalendarRange, WorkingHours } from './types.ts';
|
|
8
|
+
/** Every slot at least `duration` long where every *known* principal in
|
|
9
|
+
* `answers` is free. An unparseable `duration` (`wire.ts`'s
|
|
10
|
+
* `parseDurationMs` returning `null`) answers no slots rather than
|
|
11
|
+
* throwing — the same "do not crash a whole read over one bad value"
|
|
12
|
+
* discipline `availabilityFromWire` already follows. `principalIds` is
|
|
13
|
+
* only consulted when `workingHours` is a per-principal map, to know which
|
|
14
|
+
* principals besides `answers`' own keys (an unknown principal still gets
|
|
15
|
+
* its own working day considered, even with no busy periods to merge in)
|
|
16
|
+
* need one (wtfalch/calendar#31). */
|
|
17
|
+
export declare function findFreeSlots(answers: ReadonlyMap<string, AvailabilityResult>, range: CalendarRange, duration: string, workingHours: boolean | ReadonlyMap<string, WorkingHours>, principalIds?: readonly string[]): readonly CalendarRange[];
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The pure slot search behind `CalendarClient.findTime` (issue #13). No
|
|
3
|
+
* network and no server-shaped types here — just merging busy periods and
|
|
4
|
+
* walking the gaps between them, so the search itself is testable without a
|
|
5
|
+
* connection at all.
|
|
6
|
+
*/
|
|
7
|
+
import { parseDurationMs } from "./wire.js";
|
|
8
|
+
/** 09:00-17:00. Every busy period already arrives in UTC (`wire.ts`'s
|
|
9
|
+
* `availabilityFromWire`), so this is the fallback for `workingHours:
|
|
10
|
+
* true` and for a principal a per-attendee map (wtfalch/calendar#31)
|
|
11
|
+
* never names -- the same uniform bound the package used for everyone
|
|
12
|
+
* before that option existed (issue #13's original Decision). */
|
|
13
|
+
const WORKING_HOURS_START_UTC = 9;
|
|
14
|
+
const WORKING_HOURS_END_UTC = 17;
|
|
15
|
+
const UTC = { timeZone: 'UTC' };
|
|
16
|
+
/** Every *known* principal's busy periods, merged into one sorted,
|
|
17
|
+
* overlap-free timeline. An unknown principal contributes nothing, on
|
|
18
|
+
* purpose: this package never treats "cannot be seen" as a constraint to
|
|
19
|
+
* book around (`AvailabilityResult`'s own doc comment). */
|
|
20
|
+
function mergedBusy(answers) {
|
|
21
|
+
const raw = [];
|
|
22
|
+
for (const answer of answers.values()) {
|
|
23
|
+
if (answer.kind !== 'known')
|
|
24
|
+
continue;
|
|
25
|
+
for (const period of answer.periods) {
|
|
26
|
+
raw.push({ start: new Date(period.start).getTime(), end: new Date(period.end).getTime() });
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
raw.sort((a, b) => a.start - b.start);
|
|
30
|
+
const merged = [];
|
|
31
|
+
for (const interval of raw) {
|
|
32
|
+
const last = merged[merged.length - 1];
|
|
33
|
+
if (last && interval.start <= last.end)
|
|
34
|
+
last.end = Math.max(last.end, interval.end);
|
|
35
|
+
else
|
|
36
|
+
merged.push({ ...interval });
|
|
37
|
+
}
|
|
38
|
+
return merged;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* The UTC instant of `hour:00` on the civil date `(year, month, day)` as
|
|
42
|
+
* read in `timeZone` (wtfalch/calendar#31). Guess the instant as if
|
|
43
|
+
* `timeZone` were UTC, read what `timeZone` actually shows for that guess,
|
|
44
|
+
* and correct by the difference — one pass, no timezone database beyond
|
|
45
|
+
* what `Intl.DateTimeFormat` already carries. Exact only up to a DST
|
|
46
|
+
* transition landing on this exact hour, which is the same limitation
|
|
47
|
+
* every offset-corrected-guess conversion has without a full tz-rules
|
|
48
|
+
* engine; a wrong hour on the one or two days a year that happens is a far
|
|
49
|
+
* smaller failure than the fixed-UTC window this option replaces.
|
|
50
|
+
*/
|
|
51
|
+
function zonedHourToUtcMs(year, month, day, hour, timeZone) {
|
|
52
|
+
const guessMs = Date.UTC(year, month - 1, day, hour, 0, 0);
|
|
53
|
+
const parts = new Intl.DateTimeFormat('en-US', {
|
|
54
|
+
timeZone,
|
|
55
|
+
hourCycle: 'h23',
|
|
56
|
+
year: 'numeric',
|
|
57
|
+
month: '2-digit',
|
|
58
|
+
day: '2-digit',
|
|
59
|
+
hour: '2-digit',
|
|
60
|
+
minute: '2-digit',
|
|
61
|
+
second: '2-digit',
|
|
62
|
+
}).formatToParts(new Date(guessMs));
|
|
63
|
+
const get = (type) => Number(parts.find((part) => part.type === type)?.value ?? 0);
|
|
64
|
+
const asIfUtc = Date.UTC(get('year'), get('month') - 1, get('day'), get('hour'), get('minute'));
|
|
65
|
+
return guessMs - (asIfUtc - guessMs);
|
|
66
|
+
}
|
|
67
|
+
/** One principal's own working-day windows, one per civil day of theirs
|
|
68
|
+
* that overlaps `[rangeStart, rangeEnd)` -- walked by *their* calendar
|
|
69
|
+
* dates in `hours.timeZone`, not UTC's, so a zone far from UTC still gets
|
|
70
|
+
* its own correctly-placed window rather than one sliced by a UTC
|
|
71
|
+
* midnight that means nothing to that principal (wtfalch/calendar#31). */
|
|
72
|
+
function dailyWindows(rangeStart, rangeEnd, hours) {
|
|
73
|
+
const startHour = hours.startHour ?? WORKING_HOURS_START_UTC;
|
|
74
|
+
const endHour = hours.endHour ?? WORKING_HOURS_END_UTC;
|
|
75
|
+
const windows = [];
|
|
76
|
+
const civil = new Intl.DateTimeFormat('en-US', {
|
|
77
|
+
timeZone: hours.timeZone,
|
|
78
|
+
year: 'numeric',
|
|
79
|
+
month: '2-digit',
|
|
80
|
+
day: '2-digit',
|
|
81
|
+
}).formatToParts(new Date(rangeStart));
|
|
82
|
+
const get = (type) => Number(civil.find((part) => part.type === type)?.value ?? 0);
|
|
83
|
+
// Anchored as a UTC-noon instant per civil day, purely to step the
|
|
84
|
+
// calendar forward one day at a time with `setUTCDate` -- never read as
|
|
85
|
+
// a real instant itself.
|
|
86
|
+
const day = new Date(Date.UTC(get('year'), get('month') - 1, get('day'), 12));
|
|
87
|
+
// A year of days is far more than any sane `findTime` range asks for;
|
|
88
|
+
// it only guards a caller-supplied range from looping forever.
|
|
89
|
+
for (let i = 0; i < 366; i++) {
|
|
90
|
+
const start = zonedHourToUtcMs(day.getUTCFullYear(), day.getUTCMonth() + 1, day.getUTCDate(), startHour, hours.timeZone);
|
|
91
|
+
const end = zonedHourToUtcMs(day.getUTCFullYear(), day.getUTCMonth() + 1, day.getUTCDate(), endHour, hours.timeZone);
|
|
92
|
+
if (start >= rangeEnd)
|
|
93
|
+
break;
|
|
94
|
+
if (start < end && end > rangeStart) {
|
|
95
|
+
windows.push({ start: Math.max(start, rangeStart), end: Math.min(end, rangeEnd) });
|
|
96
|
+
}
|
|
97
|
+
day.setUTCDate(day.getUTCDate() + 1);
|
|
98
|
+
}
|
|
99
|
+
return windows;
|
|
100
|
+
}
|
|
101
|
+
/** The time covered by both `a` and `b` -- both already sorted and
|
|
102
|
+
* disjoint, so one sweep suffices. Used to fold one more principal's own
|
|
103
|
+
* working-day windows into the running candidate set: a slot must fall
|
|
104
|
+
* inside *every* named principal's own working day, not just one shared
|
|
105
|
+
* window (wtfalch/calendar#31). */
|
|
106
|
+
function intersect(a, b) {
|
|
107
|
+
const out = [];
|
|
108
|
+
let i = 0;
|
|
109
|
+
let j = 0;
|
|
110
|
+
while (i < a.length && j < b.length) {
|
|
111
|
+
const ai = a[i];
|
|
112
|
+
const bj = b[j];
|
|
113
|
+
if (!ai || !bj)
|
|
114
|
+
break;
|
|
115
|
+
const start = Math.max(ai.start, bj.start);
|
|
116
|
+
const end = Math.min(ai.end, bj.end);
|
|
117
|
+
if (start < end)
|
|
118
|
+
out.push({ start, end });
|
|
119
|
+
if (ai.end < bj.end)
|
|
120
|
+
i += 1;
|
|
121
|
+
else
|
|
122
|
+
j += 1;
|
|
123
|
+
}
|
|
124
|
+
return out;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* `range`, split into candidate windows. `workingHours`:
|
|
128
|
+
* - `false`/`undefined`: the whole range, unsplit.
|
|
129
|
+
* - `true`: one uniform 09:00-17:00 UTC window per UTC day (issue #13's
|
|
130
|
+
* original behaviour, kept for a caller with no per-principal data).
|
|
131
|
+
* - a per-principal map: the intersection of every named principal's own
|
|
132
|
+
* working day, each in their own zone and hours -- a principal in
|
|
133
|
+
* `principalIds` but absent from the map falls back to the uniform
|
|
134
|
+
* 09:00-17:00 UTC window, same as `true` (wtfalch/calendar#31).
|
|
135
|
+
*/
|
|
136
|
+
function candidateWindows(range, workingHours, principalIds) {
|
|
137
|
+
const rangeStart = new Date(range.after).getTime();
|
|
138
|
+
const rangeEnd = new Date(range.before).getTime();
|
|
139
|
+
if (rangeStart >= rangeEnd)
|
|
140
|
+
return [];
|
|
141
|
+
if (workingHours === false)
|
|
142
|
+
return [{ start: rangeStart, end: rangeEnd }];
|
|
143
|
+
if (workingHours === true)
|
|
144
|
+
return dailyWindows(rangeStart, rangeEnd, UTC);
|
|
145
|
+
let windows = [{ start: rangeStart, end: rangeEnd }];
|
|
146
|
+
for (const principalId of principalIds) {
|
|
147
|
+
const hours = workingHours.get(principalId) ?? UTC;
|
|
148
|
+
windows = intersect(windows, dailyWindows(rangeStart, rangeEnd, hours));
|
|
149
|
+
if (windows.length === 0)
|
|
150
|
+
break;
|
|
151
|
+
}
|
|
152
|
+
return windows;
|
|
153
|
+
}
|
|
154
|
+
/** One free slot per gap that fits `durationMs` — the earliest-starting fit
|
|
155
|
+
* in that gap, not every possible start inside it. `findTime` names where
|
|
156
|
+
* to look first; a start-time granularity nobody asked for would be an
|
|
157
|
+
* option this ticket does not need (issue #13 Decision). */
|
|
158
|
+
function slotsIn(window, busy, durationMs) {
|
|
159
|
+
const slots = [];
|
|
160
|
+
let cursor = window.start;
|
|
161
|
+
for (const period of busy) {
|
|
162
|
+
if (period.end <= cursor)
|
|
163
|
+
continue;
|
|
164
|
+
if (period.start >= window.end)
|
|
165
|
+
break;
|
|
166
|
+
if (period.start - cursor >= durationMs) {
|
|
167
|
+
slots.push({
|
|
168
|
+
after: new Date(cursor).toISOString(),
|
|
169
|
+
before: new Date(cursor + durationMs).toISOString(),
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
cursor = Math.max(cursor, period.end);
|
|
173
|
+
}
|
|
174
|
+
if (window.end - cursor >= durationMs) {
|
|
175
|
+
slots.push({
|
|
176
|
+
after: new Date(cursor).toISOString(),
|
|
177
|
+
before: new Date(cursor + durationMs).toISOString(),
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
return slots;
|
|
181
|
+
}
|
|
182
|
+
/** Every slot at least `duration` long where every *known* principal in
|
|
183
|
+
* `answers` is free. An unparseable `duration` (`wire.ts`'s
|
|
184
|
+
* `parseDurationMs` returning `null`) answers no slots rather than
|
|
185
|
+
* throwing — the same "do not crash a whole read over one bad value"
|
|
186
|
+
* discipline `availabilityFromWire` already follows. `principalIds` is
|
|
187
|
+
* only consulted when `workingHours` is a per-principal map, to know which
|
|
188
|
+
* principals besides `answers`' own keys (an unknown principal still gets
|
|
189
|
+
* its own working day considered, even with no busy periods to merge in)
|
|
190
|
+
* need one (wtfalch/calendar#31). */
|
|
191
|
+
export function findFreeSlots(answers, range, duration, workingHours, principalIds = [...answers.keys()]) {
|
|
192
|
+
const durationMs = parseDurationMs(duration);
|
|
193
|
+
if (!durationMs)
|
|
194
|
+
return [];
|
|
195
|
+
const busy = mergedBusy(answers);
|
|
196
|
+
const windows = candidateWindows(range, workingHours, principalIds);
|
|
197
|
+
return windows.flatMap((window) => slotsIn(window, busy, durationMs));
|
|
198
|
+
}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Export a `CalendarEvent` (or several) as an RFC 5545 `.ics` document
|
|
3
|
+
* (wtfalch/calendar#28), and `icsToEventDrafts` to import one back
|
|
4
|
+
* (wtfalch/calendar#41, the other half of agora#159,
|
|
5
|
+
* https://github.com/wtfalch/agora/issues/159). Read-only subscription feeds
|
|
6
|
+
* are still a separate, deferred gap (`PRODUCT.md`) -- `icsToEventDrafts` is
|
|
7
|
+
* a one-time parse, not a poller, and has no opinion on where its output
|
|
8
|
+
* ends up (`CalendarClient.importIcs`, `types.ts`, calls `createEvent` once
|
|
9
|
+
* per draft).
|
|
10
|
+
*
|
|
11
|
+
* **Every date-time is written in UTC (`Z`-suffixed), naively.** `start` is
|
|
12
|
+
* a local date-time with no offset, and `timeZone` says which zone it is
|
|
13
|
+
* local to -- but this package already treats every `start` as if it were
|
|
14
|
+
* UTC for its own display arithmetic (`EventDetail.tsx`'s `formatWhen`,
|
|
15
|
+
* `Calendar.tsx`'s grid rendering both do `new Date(`${event.start}Z`)`).
|
|
16
|
+
* Doing anything more accurate here -- resolving a named zone's real UTC
|
|
17
|
+
* offset -- would make this file the one place in the package that treats
|
|
18
|
+
* `timeZone` differently from everywhere else, for an event whose zone is
|
|
19
|
+
* "UTC" or unset in every fixture and every sample this package ships.
|
|
20
|
+
* `RecurrenceRule.until` shares the same treatment, which is also what RFC
|
|
21
|
+
* 5545 §3.3.10 requires: `UNTIL` must carry the same value type (UTC or
|
|
22
|
+
* not) as `DTSTART`.
|
|
23
|
+
*
|
|
24
|
+
* **`rscale`/`skip` (RFC 8984 §3.3, non-Gregorian calendars) have no RFC
|
|
25
|
+
* 5545 `RRULE` equivalent** and are silently omitted -- there is no
|
|
26
|
+
* standard part to write them into. Every other `CalendarRecurrenceRule`
|
|
27
|
+
* part round-trips (wtfalch/calendar#27's own `byDay`/`byMonthDay`/`byMonth`/
|
|
28
|
+
* `bySetPosition`/`firstDayOfWeek`/... included).
|
|
29
|
+
*
|
|
30
|
+
* **`virtualLocations` and `alerts` are not carried into the export.**
|
|
31
|
+
* Neither RFC 5545 property (`VALARM` for alerts; nothing standard for a
|
|
32
|
+
* join link distinct from `LOCATION`) was part of this ticket's evidence
|
|
33
|
+
* (`EventDetail.tsx` has no export control at all, not "an export control
|
|
34
|
+
* that drops one field"), so adding them is left to a later ticket.
|
|
35
|
+
*/
|
|
36
|
+
import type { CalendarEvent, CalendarEventDraft, ImportIcsSkippedEvent } from './types.ts';
|
|
37
|
+
export type IcsExportOptions = {
|
|
38
|
+
/** The `DTSTAMP` moment. Injectable so a caller (or a test) does not have
|
|
39
|
+
* to accept the real wall clock, mirroring `EventEditor`'s/`Calendar`'s
|
|
40
|
+
* own `now` prop. Defaults to `new Date()`. */
|
|
41
|
+
now?: Date;
|
|
42
|
+
};
|
|
43
|
+
/** One or more events as a single RFC 5545 `.ics` document (a `VCALENDAR`
|
|
44
|
+
* wrapping one `VEVENT` per event) -- CRLF line endings and folding
|
|
45
|
+
* included, so the string this returns is ready to write to a file or hand
|
|
46
|
+
* to a `Blob` exactly as is. */
|
|
47
|
+
export declare function eventsToIcs(events: readonly CalendarEvent[], options?: IcsExportOptions): string;
|
|
48
|
+
/** A single event's own `.ics` document -- `EventDetail`'s "Download .ics"
|
|
49
|
+
* control (wtfalch/calendar#28) is this, one event at a time. */
|
|
50
|
+
export declare function eventToIcs(event: CalendarEvent, options?: IcsExportOptions): string;
|
|
51
|
+
/**
|
|
52
|
+
* One `CalendarEventDraft` per `VEVENT` in an RFC 5545 `.ics` document --
|
|
53
|
+
* the inverse of `eventsToIcs` (wtfalch/calendar#41). `calendarId` on each
|
|
54
|
+
* draft is a placeholder empty string: this function only ever sees the
|
|
55
|
+
* document, never the calendar it is being imported into, so
|
|
56
|
+
* `CalendarClient.importIcs` (`calendar-client.ts`) overwrites it before
|
|
57
|
+
* calling `createEvent`.
|
|
58
|
+
*
|
|
59
|
+
* A `VEVENT` outside a `BEGIN:VCALENDAR`/`END:VCALENDAR` pair, or with no
|
|
60
|
+
* matching `END:VEVENT`, is silently not collected -- the same tolerance a
|
|
61
|
+
* hand-written or partially-truncated `.ics` file needs, since this is a
|
|
62
|
+
* one-time import rather than a validator.
|
|
63
|
+
*
|
|
64
|
+
* A `VEVENT` that parses structurally but that `veventToDraft` cannot turn
|
|
65
|
+
* into a draft (no `DTSTART`, an `RRULE` `FREQ` this package does not
|
|
66
|
+
* recognise) is caught per event and reported in `skipped` rather than
|
|
67
|
+
* thrown -- one malformed `VEVENT` used to abort the whole document and
|
|
68
|
+
* discard every other, otherwise-valid one in it (wtfalch/calendar#46).
|
|
69
|
+
*/
|
|
70
|
+
export declare function icsToEventDrafts(ics: string): {
|
|
71
|
+
readonly drafts: readonly CalendarEventDraft[];
|
|
72
|
+
readonly skipped: readonly ImportIcsSkippedEvent[];
|
|
73
|
+
};
|