@super-calendar/core 2.15.0 → 2.16.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 +41 -2
- package/dist/index.d.mts +29 -1021
- package/dist/index.d.ts +29 -1021
- package/dist/index.js +124 -1599
- package/dist/index.mjs +58 -1534
- package/dist/recurrence-BvmTFytR.js +1943 -0
- package/dist/recurrence-CvUX9ncg.mjs +1548 -0
- package/dist/timezone-d6EaWlvP.d.mts +996 -0
- package/dist/timezone-d6EaWlvP.d.ts +996 -0
- package/dist/vanilla.d.mts +2 -0
- package/dist/vanilla.d.ts +2 -0
- package/dist/vanilla.js +68 -0
- package/dist/vanilla.mjs +1 -0
- package/package.json +18 -2
- package/src/index.ts +3 -0
- package/src/types.ts +17 -2
- package/src/utils/dateRange.ts +0 -71
- package/src/utils/eventSource.ts +166 -0
- package/src/utils/labels.ts +15 -2
- package/src/utils/monthGrid.ts +0 -41
- package/src/utils/recurrence.ts +9 -10
- package/src/utils/useDateRange.ts +80 -0
- package/src/utils/useEventSource.ts +20 -41
- package/src/utils/useMonthGrid.ts +42 -0
- package/src/vanilla.ts +15 -0
|
@@ -0,0 +1,996 @@
|
|
|
1
|
+
import { Locale } from "date-fns";
|
|
2
|
+
/** The view the calendar renders: a day-column grid (`day`, `3days`, `week`, `custom`), the `month` grid, or the `schedule` list. */
|
|
3
|
+
type CalendarMode = "day" | "3days" | "week" | "custom" | "month" | "schedule" | "year";
|
|
4
|
+
/** The time-grid modes (day-column views, excluding month and schedule). */
|
|
5
|
+
type TimeGridMode = Exclude<CalendarMode, "month" | "schedule" | "year">;
|
|
6
|
+
/**
|
|
7
|
+
* The minimal shape every calendar event must have. Layout (positioning,
|
|
8
|
+
* overlap resolution, paging) only ever reads `start`/`end`; `title` is used by
|
|
9
|
+
* the built-in default renderer. Anything else lives in your own type and is
|
|
10
|
+
* threaded through untouched via the `T` generic.
|
|
11
|
+
*/
|
|
12
|
+
interface ICalendarEvent {
|
|
13
|
+
/** When the event begins. */
|
|
14
|
+
start: Date;
|
|
15
|
+
/** When the event ends. */
|
|
16
|
+
end: Date;
|
|
17
|
+
/** Display label, shown by the built-in default renderer. */
|
|
18
|
+
title?: string;
|
|
19
|
+
/**
|
|
20
|
+
* Force this event into the all-day lane (above the time grid) instead of the
|
|
21
|
+
* timed columns. When omitted, an event is treated as all-day only if it spans
|
|
22
|
+
* whole days (both `start` and `end` land on midnight).
|
|
23
|
+
*/
|
|
24
|
+
allDay?: boolean;
|
|
25
|
+
/** Ignore taps/long-presses on this event (the built-in renderer also dims it). */
|
|
26
|
+
disabled?: boolean;
|
|
27
|
+
/**
|
|
28
|
+
* Whether this event can be dragged to move or resize. Defaults to `true`, so
|
|
29
|
+
* enabling drag with `onDragEvent` makes every event movable. Set `false` to
|
|
30
|
+
* lock a specific event (a confirmed booking, someone else's event): it keeps
|
|
31
|
+
* its normal look and still responds to taps, it just can't be picked up. Use
|
|
32
|
+
* this for events that can *never* move; to reject a move only for certain
|
|
33
|
+
* targets (an overlap, an out-of-bounds slot), return `false` from `onDragEvent`
|
|
34
|
+
* instead so the event drags and snaps back.
|
|
35
|
+
*/
|
|
36
|
+
draggable?: boolean;
|
|
37
|
+
/**
|
|
38
|
+
* Whether this event can be moved (dragged to a new time/day). Defaults to the
|
|
39
|
+
* grid's `eventStartEditable` (itself `true`). Set `false` to allow only resize.
|
|
40
|
+
* A `draggable: false` event ignores this (it can neither move nor resize).
|
|
41
|
+
*/
|
|
42
|
+
startEditable?: boolean;
|
|
43
|
+
/**
|
|
44
|
+
* Whether this event can be resized (its start or end edge dragged). Defaults to
|
|
45
|
+
* the grid's `eventDurationEditable` (itself `true`). Set `false` to allow only
|
|
46
|
+
* move. A `draggable: false` event ignores this (it can neither move nor resize).
|
|
47
|
+
*/
|
|
48
|
+
durationEditable?: boolean;
|
|
49
|
+
/** Colour of this event's resize grips in the native time grid and resource timeline. Defaults to the theme's eventText colour. */
|
|
50
|
+
dragHandleColor?: string;
|
|
51
|
+
/**
|
|
52
|
+
* How the event renders. `"auto"` (default) is a normal event box/chip;
|
|
53
|
+
* `"background"` paints the event's time range as a non-interactive shaded
|
|
54
|
+
* band behind the grid instead (blocked time, holidays). Background events
|
|
55
|
+
* are excluded from chips, the agenda, and year-view dots.
|
|
56
|
+
*/
|
|
57
|
+
display?: "auto" | "background";
|
|
58
|
+
/**
|
|
59
|
+
* Repeat rule. Pass the event to `expandRecurringEvents(events, start, end)` to
|
|
60
|
+
* materialise its occurrences within a range. Calendar expands rules for its
|
|
61
|
+
* visible range; standalone views expect already expanded events.
|
|
62
|
+
*/
|
|
63
|
+
recurrence?: RecurrenceRule;
|
|
64
|
+
}
|
|
65
|
+
/** How often a recurring event repeats. */
|
|
66
|
+
type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";
|
|
67
|
+
/** A simple, RRULE-inspired repeat rule expanded by `expandRecurringEvents`. */
|
|
68
|
+
interface RecurrenceRule {
|
|
69
|
+
/** How often the event repeats. */
|
|
70
|
+
freq: RecurrenceFrequency;
|
|
71
|
+
/** Repeat every N periods. Default 1. */
|
|
72
|
+
interval?: number;
|
|
73
|
+
/** Stop after this many occurrences (including the first). */
|
|
74
|
+
count?: number;
|
|
75
|
+
/** Stop on/after this date (inclusive). */
|
|
76
|
+
until?: Date;
|
|
77
|
+
/**
|
|
78
|
+
* For `weekly`: the weekdays to repeat on (0 = Sunday … 6 = Saturday), keeping
|
|
79
|
+
* the event's time of day. Omit to repeat on the start date's own weekday.
|
|
80
|
+
*/
|
|
81
|
+
weekdays?: WeekStartsOn[];
|
|
82
|
+
/**
|
|
83
|
+
* For `monthly`/`yearly`: repeat on the Nth weekday of the period instead of the
|
|
84
|
+
* start date's day-of-month — e.g. `{ week: 3, weekday: 1 }` is the 3rd Monday.
|
|
85
|
+
* `week` is 1–5, or -1 for the last such weekday. Maps to an ordinal iCal `BYDAY`
|
|
86
|
+
* (e.g. `3MO`, `-1FR`).
|
|
87
|
+
*/
|
|
88
|
+
nthWeekday?: {
|
|
89
|
+
week: number;
|
|
90
|
+
weekday: WeekStartsOn;
|
|
91
|
+
};
|
|
92
|
+
/**
|
|
93
|
+
* For `monthly`: the day(s) of the month to repeat on — 1–31, or negative to
|
|
94
|
+
* count from the month's end (-1 is the last day, -2 the second-to-last). Days
|
|
95
|
+
* that don't exist in a given month (e.g. the 31st in February) are skipped.
|
|
96
|
+
* Takes precedence over the start date's own day-of-month. Maps to iCal
|
|
97
|
+
* `BYMONTHDAY`.
|
|
98
|
+
*/
|
|
99
|
+
monthDays?: number[];
|
|
100
|
+
/**
|
|
101
|
+
* For `yearly`: the month(s) to repeat in (1 = January … 12 = December), keeping
|
|
102
|
+
* the start date's day-of-month. Years where a listed month lacks that day are
|
|
103
|
+
* skipped. Maps to iCal `BYMONTH`.
|
|
104
|
+
*/
|
|
105
|
+
months?: number[];
|
|
106
|
+
/**
|
|
107
|
+
* Dates to skip (exceptions), dropped by `expandRecurringEvents`. A date at
|
|
108
|
+
* local midnight drops every occurrence on that calendar day (iCal
|
|
109
|
+
* `EXDATE;VALUE=DATE`); a date with a time drops only the occurrence starting
|
|
110
|
+
* at that exact instant. Corollary: an occurrence that itself starts at
|
|
111
|
+
* midnight can only be excluded day-wide. Maps to iCal `EXDATE`.
|
|
112
|
+
*/
|
|
113
|
+
exdates?: Date[];
|
|
114
|
+
/**
|
|
115
|
+
* Extra one-off start dates added to the set, even ones the rule wouldn't
|
|
116
|
+
* produce. Merged in chronological order and de-duplicated against rule
|
|
117
|
+
* occurrences; `exdates` still apply. Maps to iCal `RDATE`.
|
|
118
|
+
*/
|
|
119
|
+
rdates?: Date[];
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* An event carrying arbitrary extra fields `T` alongside the required shape.
|
|
123
|
+
* `ICalendarEvent` is authoritative: keys it reserves (`start`/`end`/`title`)
|
|
124
|
+
* cannot be re-typed by `T`.
|
|
125
|
+
*/
|
|
126
|
+
type CalendarEvent<T = unknown> = ICalendarEvent & Omit<T, keyof ICalendarEvent>;
|
|
127
|
+
/** Build a stable key for an event. Defaults to start-time + index. */
|
|
128
|
+
type EventKeyExtractor<T = unknown> = (event: CalendarEvent<T>, index: number) => string;
|
|
129
|
+
/** Sunday = 0 … Saturday = 6, matching `Date.prototype.getDay()`. */
|
|
130
|
+
type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
|
|
131
|
+
/**
|
|
132
|
+
* A day's open hours for `businessHours` shading, as hours (fractions allowed,
|
|
133
|
+
* e.g. `9.5`): a single window `{ start, end }`, or an array of windows to leave
|
|
134
|
+
* a closed gap between them (a lunch break: `[{ start: 9, end: 12 }, { start: 13,
|
|
135
|
+
* end: 17 }]`). Everything outside the window(s) is shaded closed.
|
|
136
|
+
*/
|
|
137
|
+
type BusinessHoursValue = {
|
|
138
|
+
start: number;
|
|
139
|
+
end: number;
|
|
140
|
+
} | {
|
|
141
|
+
start: number;
|
|
142
|
+
end: number;
|
|
143
|
+
}[] | null;
|
|
144
|
+
/**
|
|
145
|
+
* The `businessHours` callback: return the open hours for `date` (see
|
|
146
|
+
* {@link BusinessHoursValue}), `null` when the day is fully closed (all shaded),
|
|
147
|
+
* or `undefined` for no business-hours shading. Shared by both renderers; pair
|
|
148
|
+
* with `closedHourBands` to get the spans to shade.
|
|
149
|
+
*/
|
|
150
|
+
type BusinessHours = (date: Date) => BusinessHoursValue;
|
|
151
|
+
/**
|
|
152
|
+
* One closed-hours band handed to a `renderBusinessHours` override: the day it
|
|
153
|
+
* belongs to and its span as fractional hours, already clamped to the visible
|
|
154
|
+
* window. `ResourceTimeline` extends it with the lane's resource.
|
|
155
|
+
*/
|
|
156
|
+
interface BusinessHoursBand {
|
|
157
|
+
date: Date;
|
|
158
|
+
start: number;
|
|
159
|
+
end: number;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Props passed to a `renderCreateGhost` component while a drag-to-create sweep is
|
|
163
|
+
* in progress. `start` and `end` are the snapped range `onCreateEvent` would
|
|
164
|
+
* receive if the pointer were released at its current position: ordered, at
|
|
165
|
+
* least one snap step long, and clamped to the pressed day. They can extend past
|
|
166
|
+
* a narrowed visible-hour window, where the preview box itself stops at the edge.
|
|
167
|
+
* `ResourceTimeline` adds the lane's resource.
|
|
168
|
+
*/
|
|
169
|
+
interface CreateGhostArgs {
|
|
170
|
+
/** Start of the range the sweep would create. */
|
|
171
|
+
start: Date;
|
|
172
|
+
/** End of the range the sweep would create. */
|
|
173
|
+
end: Date;
|
|
174
|
+
}
|
|
175
|
+
/** Options for {@link CalendarHandle.scrollToTime}. */
|
|
176
|
+
interface ScrollToTimeOptions {
|
|
177
|
+
/** Animate the scroll. Default true; off when the OS asks to reduce motion. */
|
|
178
|
+
animated?: boolean;
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* Imperative methods exposed through a `ref` on `Calendar` and `TimeGrid`.
|
|
182
|
+
*/
|
|
183
|
+
interface CalendarHandle {
|
|
184
|
+
/**
|
|
185
|
+
* Scroll the time grid so `minutes` (from midnight) sits at the top of the
|
|
186
|
+
* hours, at the current zoom. Works with any value, including the one already
|
|
187
|
+
* passed as `scrollOffsetMinutes`. A no-op when no time grid is showing.
|
|
188
|
+
*/
|
|
189
|
+
scrollToTime(minutes: number, options?: ScrollToTimeOptions): void;
|
|
190
|
+
}
|
|
191
|
+
/** The shared colour palette both renderers derive their themes from. */
|
|
192
|
+
interface CalendarColors {
|
|
193
|
+
/** Opaque surface behind floating chrome (e.g. the date-picker field and popover). */
|
|
194
|
+
surface: string;
|
|
195
|
+
/** Hour lines, day separators and month-cell borders. */
|
|
196
|
+
gridLine: string;
|
|
197
|
+
/** Background tint behind weekend columns/cells. */
|
|
198
|
+
weekendBackground: string;
|
|
199
|
+
/** Background tint over hours outside business hours (time grid). */
|
|
200
|
+
outsideHoursBackground: string;
|
|
201
|
+
/** Today badge fill. */
|
|
202
|
+
todayBackground: string;
|
|
203
|
+
/** Today badge text. */
|
|
204
|
+
todayText: string;
|
|
205
|
+
/** Selected day / range-endpoint badge fill. */
|
|
206
|
+
selectedBackground: string;
|
|
207
|
+
/** Selected day / range-endpoint badge text. */
|
|
208
|
+
selectedText: string;
|
|
209
|
+
/** Band behind a selected range. */
|
|
210
|
+
rangeBackground: string;
|
|
211
|
+
/** Hover highlight behind a day (DOM, mouse only). */
|
|
212
|
+
hoverBackground: string;
|
|
213
|
+
/** Current-time indicator line (time grid). */
|
|
214
|
+
nowIndicator: string;
|
|
215
|
+
/** Primary text (day numbers, weekday labels). */
|
|
216
|
+
text: string;
|
|
217
|
+
/** Muted text (hour labels, "+N more"). */
|
|
218
|
+
textMuted: string;
|
|
219
|
+
/** Dimmed text for disabled / adjacent-month days. */
|
|
220
|
+
textDisabled: string;
|
|
221
|
+
/** Default event chip fill. */
|
|
222
|
+
eventBackground: string;
|
|
223
|
+
/** Default event chip text. */
|
|
224
|
+
eventText: string;
|
|
225
|
+
/** Shaded band behind a `display: "background"` event. */
|
|
226
|
+
backgroundEvent: string;
|
|
227
|
+
}
|
|
228
|
+
/** The default light-theme colour palette. */
|
|
229
|
+
declare const lightColors: CalendarColors;
|
|
230
|
+
/** The default dark-theme colour palette. */
|
|
231
|
+
declare const darkColors: CalendarColors;
|
|
232
|
+
/** Which range-band shape a day shows. */
|
|
233
|
+
type RangeBandKind = "none" | "fill" | "pill-start" | "pill-mid" | "pill-end";
|
|
234
|
+
/** The band shape for a day, given the fill-cell option. */
|
|
235
|
+
declare function rangeBandKind(day: {
|
|
236
|
+
isInRange: boolean;
|
|
237
|
+
isRangeStart: boolean;
|
|
238
|
+
isRangeEnd: boolean;
|
|
239
|
+
}, fillCell: boolean): RangeBandKind;
|
|
240
|
+
/** Whether a band shape rounds its leading / trailing edge (pill ends). */
|
|
241
|
+
declare function bandRounding(kind: RangeBandKind): {
|
|
242
|
+
start: boolean;
|
|
243
|
+
end: boolean;
|
|
244
|
+
};
|
|
245
|
+
/** Which filled badge a day shows (today wins over a selection). */
|
|
246
|
+
type DayBadgeKind = "none" | "today" | "selected";
|
|
247
|
+
/**
|
|
248
|
+
* The filled-badge kind for a day. `isSelected` is true for both range endpoints
|
|
249
|
+
* and discrete selected days; today always wins when it coincides.
|
|
250
|
+
*/
|
|
251
|
+
declare function dayBadgeKind(day: {
|
|
252
|
+
isSelected: boolean;
|
|
253
|
+
}, isToday: boolean): DayBadgeKind;
|
|
254
|
+
/** A selected span. `end` is `null` while only the first endpoint has been picked. */
|
|
255
|
+
interface DateRange {
|
|
256
|
+
/** The first endpoint. */
|
|
257
|
+
start: Date;
|
|
258
|
+
/** The second endpoint, or `null` while only the first has been picked. */
|
|
259
|
+
end: Date | null;
|
|
260
|
+
}
|
|
261
|
+
/** Limits applied before a date can be selected. */
|
|
262
|
+
interface DateSelectionConstraints {
|
|
263
|
+
/** Earliest selectable day (inclusive). */
|
|
264
|
+
minDate?: Date;
|
|
265
|
+
/** Latest selectable day (inclusive). */
|
|
266
|
+
maxDate?: Date;
|
|
267
|
+
/** Return true to forbid selecting a specific day. */
|
|
268
|
+
isDateDisabled?: (date: Date) => boolean;
|
|
269
|
+
}
|
|
270
|
+
/** Whether `date` passes the min/max/disabled constraints (compared by calendar day). */
|
|
271
|
+
declare function isDateSelectable(date: Date, constraints?: DateSelectionConstraints): boolean;
|
|
272
|
+
/**
|
|
273
|
+
* The range after pressing `pressed`, mirroring the familiar date-picker model:
|
|
274
|
+
* - no range yet, or a complete range exists → start fresh (`{ start: pressed, end: null }`),
|
|
275
|
+
* so a third press resets the selection.
|
|
276
|
+
* - an open range (a start but no end) → close it, auto-swapping when the press
|
|
277
|
+
* precedes the start so `start <= end` always holds.
|
|
278
|
+
*
|
|
279
|
+
* Returns `current` unchanged when `pressed` isn't selectable.
|
|
280
|
+
*/
|
|
281
|
+
declare function nextDateRange(current: DateRange | null, pressed: Date, constraints?: DateSelectionConstraints): DateRange | null;
|
|
282
|
+
/** True when `date` is one of the range's two endpoints. */
|
|
283
|
+
declare function isRangeEndpoint(date: Date, range: DateRange | null): boolean;
|
|
284
|
+
/** True when `date` falls within a complete range (endpoints included). */
|
|
285
|
+
declare function isWithinDateRange(date: Date, range: DateRange | null): boolean;
|
|
286
|
+
/** The selection/disabled flags for one day. */
|
|
287
|
+
interface DaySelectionState {
|
|
288
|
+
/** Fails the min/max/disabled constraints. */
|
|
289
|
+
isDisabled: boolean;
|
|
290
|
+
/** A `selectedDates` day or a range endpoint (and not disabled). */
|
|
291
|
+
isSelected: boolean;
|
|
292
|
+
/** Inside a complete range, endpoints included (and not disabled). */
|
|
293
|
+
isInRange: boolean;
|
|
294
|
+
/** The range's start endpoint (and not disabled). */
|
|
295
|
+
isRangeStart: boolean;
|
|
296
|
+
/** The range's end endpoint (and not disabled). */
|
|
297
|
+
isRangeEnd: boolean;
|
|
298
|
+
}
|
|
299
|
+
/**
|
|
300
|
+
* The canonical per-day selection state, shared by `MonthView` (rendering) and
|
|
301
|
+
* `buildMonthGrid` (the headless grid) so the built-in views and a custom
|
|
302
|
+
* calendar can never disagree on what a day's state is.
|
|
303
|
+
*/
|
|
304
|
+
declare function daySelectionState(date: Date, selection: {
|
|
305
|
+
selectedDates?: Date[];
|
|
306
|
+
selectedRange?: DateRange | null;
|
|
307
|
+
}, constraints?: DateSelectionConstraints): DaySelectionState;
|
|
308
|
+
/**
|
|
309
|
+
* Per-day state shared with the month grid via context: the current selection
|
|
310
|
+
* plus the selectability constraints. Threaded through context (not props) so
|
|
311
|
+
* cached/virtualized day cells still repaint when any of it changes.
|
|
312
|
+
*/
|
|
313
|
+
interface CalendarSelection extends DateSelectionConstraints {
|
|
314
|
+
/** Selected discrete days (single or multiple). */
|
|
315
|
+
selectedDates?: Date[];
|
|
316
|
+
/** Selected span. */
|
|
317
|
+
selectedRange?: DateRange;
|
|
318
|
+
}
|
|
319
|
+
/** Options for {@link useDateRange}. */
|
|
320
|
+
interface UseDateRangeOptions extends DateSelectionConstraints {
|
|
321
|
+
/** Pre-select a range on mount. */
|
|
322
|
+
initialRange?: DateRange | null;
|
|
323
|
+
}
|
|
324
|
+
/** The seven dates of the week containing `date`, starting on `weekStartsOn`. */
|
|
325
|
+
declare const getWeekDays: (date: Date, weekStartsOn: WeekStartsOn) => Date[];
|
|
326
|
+
/** How many day columns a time-grid mode shows. `custom` uses `numberOfDays`. */
|
|
327
|
+
declare const viewDayCount: (mode: CalendarMode, numberOfDays?: number) => number;
|
|
328
|
+
/**
|
|
329
|
+
* Days in the inclusive span from `weekStartsOn` to `weekEndsOn` (1–7),
|
|
330
|
+
* wrapping when the end precedes the start (e.g. Sat→Wed). Mirrors
|
|
331
|
+
* react-native-big-calendar's `weekDaysCount`.
|
|
332
|
+
*/
|
|
333
|
+
declare const weekDaysCount: (weekStartsOn: WeekStartsOn, weekEndsOn: WeekStartsOn) => number;
|
|
334
|
+
/**
|
|
335
|
+
* The day columns to render for a time-grid page. `week` spans the calendar week
|
|
336
|
+
* (honouring `weekStartsOn`). `custom` with a `weekEndsOn` spans the partial week
|
|
337
|
+
* from `weekStartsOn` to `weekEndsOn` (anchored to `date`'s week, paging by week);
|
|
338
|
+
* otherwise every mode shows `viewDayCount` consecutive days starting at `date`.
|
|
339
|
+
*/
|
|
340
|
+
declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn, hiddenDays?: number[]) => Date[];
|
|
341
|
+
/**
|
|
342
|
+
* The calendar weeks covering `month`, padded to whole weeks starting on
|
|
343
|
+
* `weekStartsOn`. `showSixWeeks` always returns six rows (42 days) for a
|
|
344
|
+
* fixed-height grid; `isRTL` reverses each week's day order.
|
|
345
|
+
*/
|
|
346
|
+
declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, { showSixWeeks, isRTL, hiddenDays }?: {
|
|
347
|
+
showSixWeeks?: boolean;
|
|
348
|
+
isRTL?: boolean;
|
|
349
|
+
hiddenDays?: number[];
|
|
350
|
+
}) => Date[][];
|
|
351
|
+
/**
|
|
352
|
+
* Drop the days whose weekday (0=Sunday…6=Saturday) is listed in `hiddenDays`.
|
|
353
|
+
* Hiding all seven weekdays is treated as hiding nothing (matching
|
|
354
|
+
* `getViewDays`), so a misconfiguration degrades to the full grid, not a blank.
|
|
355
|
+
*/
|
|
356
|
+
declare const filterHiddenDays: (days: Date[], hiddenDays?: number[]) => Date[];
|
|
357
|
+
/** True when `date` is a Saturday or Sunday. */
|
|
358
|
+
declare const isWeekend: (date: Date) => boolean;
|
|
359
|
+
/** True when `date` falls on the current calendar day. */
|
|
360
|
+
declare const getIsToday: (date: Date) => boolean;
|
|
361
|
+
/** True when `a` and `b` are the same calendar day (ignoring the time of day). */
|
|
362
|
+
declare const isSameCalendarDay: (a: Date, b: Date) => boolean;
|
|
363
|
+
/** Minutes elapsed since midnight (0–1439). */
|
|
364
|
+
declare const minutesIntoDay: (date: Date) => number;
|
|
365
|
+
/** The twelve month anchors (first-of-month) of `date`'s year, January first. */
|
|
366
|
+
declare const getYearMonths: (date: Date) => Date[];
|
|
367
|
+
/**
|
|
368
|
+
* True when two time ranges overlap. Edges touching (one ends exactly when the
|
|
369
|
+
* next begins) do not count as an overlap. Compares absolute instants, so events
|
|
370
|
+
* at the same wall-clock time on different days do not overlap.
|
|
371
|
+
*/
|
|
372
|
+
declare function eventsOverlap(aStart: Date, aEnd: Date, bStart: Date, bEnd: Date): boolean;
|
|
373
|
+
/**
|
|
374
|
+
* True when the range `[start, end)` would overlap any event in `events` other
|
|
375
|
+
* than `moved` (compared by reference). Used by the `eventOverlap` guard to reject
|
|
376
|
+
* a drag/resize that would land an event on top of another.
|
|
377
|
+
*/
|
|
378
|
+
declare function overlapsOtherEvents<T>(events: readonly CalendarEvent<T>[], moved: CalendarEvent<T>, start: Date, end: Date): boolean;
|
|
379
|
+
/**
|
|
380
|
+
* How many calendar days one time-grid page spans, used to advance the view by a
|
|
381
|
+
* whole page (e.g. when dragging an event past the edge into the next week).
|
|
382
|
+
* Deliberately ignores `hiddenDays` so a week always steps 7, matching the
|
|
383
|
+
* keyboard PageUp/PageDown paging and `Calendar`'s own page step.
|
|
384
|
+
*/
|
|
385
|
+
declare function pageStepDays(mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number): number;
|
|
386
|
+
/**
|
|
387
|
+
* Minutes to shift an event, snapping a vertical pixel drag to the nearest
|
|
388
|
+
* `stepMinutes`. Runs on the UI thread inside the drag gesture. Returns 0 for a
|
|
389
|
+
* degenerate grid (non-positive height/step).
|
|
390
|
+
*/
|
|
391
|
+
declare function snapDeltaMinutes(translationPx: number, cellHeightPx: number, stepMinutes: number): number;
|
|
392
|
+
/**
|
|
393
|
+
* Where a moved event may start, in minutes from midnight, given the grid's
|
|
394
|
+
* visible hour window. A move keeps its duration, so only the start is held
|
|
395
|
+
* inside the window: it can reach one `snapMinutes` step before `maxHour`, and
|
|
396
|
+
* the end is free to run past the end of the day, continuing on the following
|
|
397
|
+
* day. That keeps the event starting in the column it was dropped on (a
|
|
398
|
+
* cross-day *move* is the horizontal drag) while still allowing a range that
|
|
399
|
+
* spans midnight. Runs on the UI thread inside the drag gesture.
|
|
400
|
+
*/
|
|
401
|
+
declare function clampMoveStartMinutes(startMinutes: number, minHour: number, maxHour: number, snapMinutes: number): number;
|
|
402
|
+
/**
|
|
403
|
+
* A copy of `date` shifted by `minutes` (may be negative) on the clock, so a
|
|
404
|
+
* shift across a DST change keeps the clock time. When the resulting clock time
|
|
405
|
+
* occurs twice (the hour a fall-back change repeats), the occurrence nearer to
|
|
406
|
+
* `minutes` of elapsed time wins.
|
|
407
|
+
*/
|
|
408
|
+
declare function shiftMinutes(date: Date, minutes: number): Date;
|
|
409
|
+
/**
|
|
410
|
+
* Where moving `[start, end]` by `minutes` on the clock lands, in clock hours:
|
|
411
|
+
* how far the start moves, and how many rows the moved span covers. The span
|
|
412
|
+
* keeps its elapsed duration, as {@link resolveDraggedBounds} commits a move, so
|
|
413
|
+
* gaining or losing a DST change changes its row count, and a start that lands
|
|
414
|
+
* in the hour a spring-forward change skips moves on past it. The row count is
|
|
415
|
+
* at least the layout's minimum box, as the committed event will be drawn.
|
|
416
|
+
* Worklet-safe, for live drag previews.
|
|
417
|
+
*/
|
|
418
|
+
declare function movedClockSpan(start: Date, end: Date, minutes: number): {
|
|
419
|
+
startHours: number;
|
|
420
|
+
hours: number;
|
|
421
|
+
};
|
|
422
|
+
/**
|
|
423
|
+
* Resolve a committed drag into the event's new bounds: `start` shifts by
|
|
424
|
+
* `deltaStartMinutes`, `end` by `deltaEndMinutes` (a move passes the same delta
|
|
425
|
+
* to both and preserves elapsed duration, including across DST; a resize passes
|
|
426
|
+
* 0 for the unchanged edge). Returns `null` only when the change
|
|
427
|
+
* would *shrink* the event below one `snapMinutes` step, so a resize can't commit
|
|
428
|
+
* a degenerate duration; a pure move (both deltas equal) keeps its duration and is
|
|
429
|
+
* never rejected, even for an already sub-step event. Pure, so the commit path is
|
|
430
|
+
* unit-testable without a running gesture.
|
|
431
|
+
*/
|
|
432
|
+
declare function resolveDraggedBounds(start: Date, end: Date, deltaStartMinutes: number, deltaEndMinutes: number, snapMinutes: number): {
|
|
433
|
+
start: Date;
|
|
434
|
+
end: Date;
|
|
435
|
+
} | null;
|
|
436
|
+
/**
|
|
437
|
+
* The all-day range swept out between two day cells of the month grid, ordered
|
|
438
|
+
* whichever way the sweep ran: `start` is midnight of the first day and `end` is
|
|
439
|
+
* midnight after the last, so a one-day sweep still yields a usable event. Shared
|
|
440
|
+
* by both renderers so a month drag-to-create means the same thing on each.
|
|
441
|
+
*/
|
|
442
|
+
declare function monthCreateRange(anchor: Date, hover: Date): {
|
|
443
|
+
start: Date;
|
|
444
|
+
end: Date;
|
|
445
|
+
};
|
|
446
|
+
/**
|
|
447
|
+
* The new bounds for an event picked up on `fromDay` and dropped on `toDay` in
|
|
448
|
+
* the month grid: both ends move by the same number of calendar days, so the
|
|
449
|
+
* event keeps its time of day and duration (DST included). Returns `null` when
|
|
450
|
+
* the drop lands on the day it started, so a stray drag commits nothing.
|
|
451
|
+
*/
|
|
452
|
+
declare function monthDropBounds<T>(event: CalendarEvent<T>, fromDay: Date, toDay: Date): {
|
|
453
|
+
start: Date;
|
|
454
|
+
end: Date;
|
|
455
|
+
} | null;
|
|
456
|
+
/**
|
|
457
|
+
* The start/end of a new event swept out on `day` by dragging from `startPx` to
|
|
458
|
+
* `endPx` (vertical pixels from the grid's top, i.e. the `minHour` line). Both
|
|
459
|
+
* ends snap to `snapMinutes`; the range is ordered (drag up or down) and widened
|
|
460
|
+
* to at least one step so a stationary press still yields a usable event.
|
|
461
|
+
* Returns `null` for a degenerate grid (non-positive height/step). Pure, so the
|
|
462
|
+
* commit path is unit-testable without a running gesture.
|
|
463
|
+
*/
|
|
464
|
+
declare function cellRangeFromDrag(day: Date, startPx: number, endPx: number, cellHeightPx: number, minHour: number, snapMinutes: number): {
|
|
465
|
+
start: Date;
|
|
466
|
+
end: Date;
|
|
467
|
+
} | null;
|
|
468
|
+
/**
|
|
469
|
+
* Words the built-in views add to their screen-reader labels and gutter text.
|
|
470
|
+
* The date parts are formatted through `locale`; these words are not, so pass
|
|
471
|
+
* translations through the `labels` prop to localize them. Shared by both
|
|
472
|
+
* renderers, so a translation reads the same on web and native.
|
|
473
|
+
*/
|
|
474
|
+
interface CalendarLabels {
|
|
475
|
+
/** Appended to a day's label when it is today. Default "today". */
|
|
476
|
+
today: string;
|
|
477
|
+
/** Appended to a day's label when it is selected. Default "selected". */
|
|
478
|
+
selected: string;
|
|
479
|
+
/** Appended to a day's label when it is disabled. Default "unavailable". */
|
|
480
|
+
unavailable: string;
|
|
481
|
+
/** Appended to a year-view day's label when it has events. Default "has events". */
|
|
482
|
+
hasEvents: string;
|
|
483
|
+
/** How many events a month-view day holds. Default "1 event" / "N events". */
|
|
484
|
+
eventCount: (count: number) => string;
|
|
485
|
+
/** The "+N more" overflow control's label. Default "N more events". */
|
|
486
|
+
moreEvents: (count: number) => string;
|
|
487
|
+
/** The all-day gutter text in the time grid. Default "all-day". */
|
|
488
|
+
allDay: string;
|
|
489
|
+
/**
|
|
490
|
+
* Spoken in an all-day event's label (e.g. "Trip, all day"). Default "all day".
|
|
491
|
+
* On native, a `Calendar` `allDayLabel` takes precedence.
|
|
492
|
+
*/
|
|
493
|
+
allDayEvent: string;
|
|
494
|
+
/** A timed event's spoken range from its formatted times. Default "09:00 to 10:00". */
|
|
495
|
+
timeRange: (start: string, end: string) => string;
|
|
496
|
+
/** The close control of the "+N more" popover. Default "Close". */
|
|
497
|
+
close: string;
|
|
498
|
+
/** Screen-reader action that moves an event later by `minutes`. Default "Move 15 minutes later". */
|
|
499
|
+
moveLater: (minutes: number) => string;
|
|
500
|
+
/** Screen-reader action that moves an event earlier by `minutes`. Default "Move 15 minutes earlier". */
|
|
501
|
+
moveEarlier: (minutes: number) => string;
|
|
502
|
+
/** Screen-reader action that lengthens an event by `minutes`. Default "Extend by 15 minutes". */
|
|
503
|
+
extend: (minutes: number) => string;
|
|
504
|
+
/** Screen-reader action that shortens an event by `minutes`. Default "Shorten by 15 minutes". */
|
|
505
|
+
shorten: (minutes: number) => string;
|
|
506
|
+
/**
|
|
507
|
+
* Screen-reader action that moves an event one page forward, given the page's
|
|
508
|
+
* day count and the view mode. Default "Move to next week" in week mode, else
|
|
509
|
+
* "Move to next day" / "Move to next 3 days".
|
|
510
|
+
*/
|
|
511
|
+
moveToNextPage: (days: number, mode: CalendarMode) => string;
|
|
512
|
+
/** The backward counterpart of `moveToNextPage`. Default "Move to previous week". */
|
|
513
|
+
moveToPreviousPage: (days: number, mode: CalendarMode) => string;
|
|
514
|
+
/** Resource timeline action that moves an event to another lane. Default "Move to Room A". */
|
|
515
|
+
moveToResource: (title: string) => string;
|
|
516
|
+
/**
|
|
517
|
+
* Names the web renderers' move and resize actions button and dialog for an
|
|
518
|
+
* event, given its title (empty when it has none). Default "Move or resize
|
|
519
|
+
* Planning", or "Move or resize event" without a title.
|
|
520
|
+
*/
|
|
521
|
+
eventActions?: (title: string) => string;
|
|
522
|
+
/** Opens the web event chooser for move and resize actions. Default "Edit events". */
|
|
523
|
+
editEvents?: string;
|
|
524
|
+
/** Feedback when a web move or resize is rejected. */
|
|
525
|
+
eventChangeRejected?: string;
|
|
526
|
+
}
|
|
527
|
+
/** The built-in English {@link CalendarLabels}. */
|
|
528
|
+
declare const defaultCalendarLabels: Required<CalendarLabels>;
|
|
529
|
+
/** Fill the labels a consumer left out with {@link defaultCalendarLabels}. */
|
|
530
|
+
declare function resolveCalendarLabels(labels?: Partial<CalendarLabels>): Required<CalendarLabels>;
|
|
531
|
+
/**
|
|
532
|
+
* Screen-reader label for a day: the formatted date followed by its state
|
|
533
|
+
* words, joined with ", " (e.g. "Friday, 17 July 2026, today, 3 events").
|
|
534
|
+
*/
|
|
535
|
+
declare function dayAccessibilityLabel(args: {
|
|
536
|
+
/** The date, already formatted with the consumer's locale. */
|
|
537
|
+
dateLabel: string;
|
|
538
|
+
isToday?: boolean;
|
|
539
|
+
isSelected?: boolean;
|
|
540
|
+
isDisabled?: boolean;
|
|
541
|
+
hasEvents?: boolean;
|
|
542
|
+
/** Event count to announce; omit to leave the count out. */
|
|
543
|
+
eventCount?: number;
|
|
544
|
+
labels: CalendarLabels;
|
|
545
|
+
}): string;
|
|
546
|
+
/**
|
|
547
|
+
* Minimum event-box height (px) before the built-in renderer shows the time line
|
|
548
|
+
* on a narrow multi-column timed grid. Tied to the default theme's font sizes.
|
|
549
|
+
*/
|
|
550
|
+
declare const MIN_BOX_HEIGHT_FOR_TIME = 56;
|
|
551
|
+
/** Hard-clip an overflowing title by default; opt into a trailing ellipsis. */
|
|
552
|
+
declare function titleEllipsizeMode(ellipsizeTitle: boolean): "clip" | "tail";
|
|
553
|
+
/**
|
|
554
|
+
* Screen-reader label for an event: its title followed by "all day" or its time
|
|
555
|
+
* range (which the grid otherwise only conveys visually). Empty title is dropped.
|
|
556
|
+
*/
|
|
557
|
+
declare function eventAccessibilityLabel(args: {
|
|
558
|
+
title?: string;
|
|
559
|
+
isAllDay: boolean;
|
|
560
|
+
start: Date;
|
|
561
|
+
end: Date;
|
|
562
|
+
ampm: boolean;
|
|
563
|
+
/** Spoken text for an all-day event. Default `labels.allDayEvent`. */
|
|
564
|
+
allDayLabel?: string;
|
|
565
|
+
/** Words for the all-day text and the time range. Default English. */
|
|
566
|
+
labels?: CalendarLabels;
|
|
567
|
+
}): string;
|
|
568
|
+
/**
|
|
569
|
+
* Context describing how an event is being rendered, passed to a consumer's
|
|
570
|
+
* {@link EventAccessibilityLabeler} so the label can adapt to the view (e.g. omit
|
|
571
|
+
* the time in month mode, or read the 12-hour clock when `ampm` is set).
|
|
572
|
+
*/
|
|
573
|
+
interface EventAccessibilityLabelContext {
|
|
574
|
+
/** The view the event is rendered in. */
|
|
575
|
+
mode: CalendarMode;
|
|
576
|
+
/** Whether the event sits in the all-day lane (or is an all-day event in month view). */
|
|
577
|
+
isAllDay: boolean;
|
|
578
|
+
/** Whether times are formatted as 12-hour AM/PM. */
|
|
579
|
+
ampm: boolean;
|
|
580
|
+
}
|
|
581
|
+
/**
|
|
582
|
+
* Override for an event's screen-reader label. Return the full text to announce
|
|
583
|
+
* for `event`; each renderer uses it verbatim in place of the built-in
|
|
584
|
+
* {@link eventAccessibilityLabel}. Shared by both renderers, so a custom label
|
|
585
|
+
* reads the same on web and native.
|
|
586
|
+
*/
|
|
587
|
+
type EventAccessibilityLabeler<T = unknown> = (event: CalendarEvent<T>, context: EventAccessibilityLabelContext) => string;
|
|
588
|
+
/**
|
|
589
|
+
* Month cells and the all-day lane show a single clipped line; timed-grid titles
|
|
590
|
+
* (`undefined`) wrap to fill the box.
|
|
591
|
+
*/
|
|
592
|
+
declare function titleNumberOfLines(mode: CalendarMode, isAllDay: boolean): number | undefined;
|
|
593
|
+
/**
|
|
594
|
+
* The secondary line under the title in the built-in renderer, or `null` when
|
|
595
|
+
* none should show. Timed events get their `start - end` range. An all-day event
|
|
596
|
+
* gets the literal "All day" in the schedule (which has no all-day lane to
|
|
597
|
+
* signal it positionally) and nothing on the day/week grid (the lane already
|
|
598
|
+
* does). Month cells and `showTime={false}` always return `null`.
|
|
599
|
+
*/
|
|
600
|
+
declare function eventTimeLabel(args: {
|
|
601
|
+
mode: CalendarMode;
|
|
602
|
+
isAllDay: boolean;
|
|
603
|
+
start: Date;
|
|
604
|
+
end: Date;
|
|
605
|
+
ampm: boolean;
|
|
606
|
+
showTime: boolean;
|
|
607
|
+
/** Text for an all-day event in the schedule. Default "All day". */
|
|
608
|
+
allDayLabel?: string;
|
|
609
|
+
}): string | null;
|
|
610
|
+
/**
|
|
611
|
+
* The default hour-axis label shared by both renderers' time grids, so the gutter
|
|
612
|
+
* reads the same on each: 24-hour "HH:00" (e.g. "08:00"), or a compact 12-hour
|
|
613
|
+
* "h AM/PM" (e.g. "8 AM") when `ampm` is set. Exported so a custom hour renderer
|
|
614
|
+
* can reuse the same formatting.
|
|
615
|
+
*/
|
|
616
|
+
declare function formatHour(hour: number, opts?: {
|
|
617
|
+
ampm?: boolean;
|
|
618
|
+
}): string;
|
|
619
|
+
/**
|
|
620
|
+
* Whether the time line fits in the box. The wide `day` column and contexts with
|
|
621
|
+
* no live box height (e.g. schedule, where `boxHeightPx` is undefined) always
|
|
622
|
+
* show it; narrow multi-column modes only once the box is at least
|
|
623
|
+
* {@link MIN_BOX_HEIGHT_FOR_TIME} tall. Runs on the UI thread inside the event
|
|
624
|
+
* renderer's animated style.
|
|
625
|
+
*/
|
|
626
|
+
declare function isTimeVisibleAtHeight(boxHeightPx: number | undefined, mode: CalendarMode): boolean;
|
|
627
|
+
/** Layout for the built-in timed-grid event chip at a given box height. */
|
|
628
|
+
type EventChipLayout = {
|
|
629
|
+
/**
|
|
630
|
+
* Max whole title lines that fit in the box. `0` means "no clamp" (the box
|
|
631
|
+
* height is unknown, e.g. the schedule), so the title may wrap freely.
|
|
632
|
+
*/
|
|
633
|
+
titleMaxLines: number;
|
|
634
|
+
/** Whether the secondary time line still has room below the title. */
|
|
635
|
+
showTime: boolean;
|
|
636
|
+
};
|
|
637
|
+
/**
|
|
638
|
+
* Lay out the built-in timed-grid event chip for a box of `boxHeightPx`: how
|
|
639
|
+
* many whole title lines fit, and whether the time line still has room below
|
|
640
|
+
* them. The title is primary, so the title fills the box in whole lines (never a
|
|
641
|
+
* half-cropped line) and the time only shows once a full line is left over. Pass
|
|
642
|
+
* `titleLineHeightPx`/`timeLineHeightPx` matching the rendered line heights so
|
|
643
|
+
* the clamp lands on a line boundary.
|
|
644
|
+
*
|
|
645
|
+
* Worklet-safe, so the native renderer can drive the title's max-height on the UI
|
|
646
|
+
* thread as the grid zooms; the dom renderer calls it with its static box height.
|
|
647
|
+
* A `boxHeightPx` of `undefined` (the schedule has no live box height) returns
|
|
648
|
+
* `titleMaxLines: 0` (no clamp) with the unconditional time visibility.
|
|
649
|
+
*/
|
|
650
|
+
declare function eventChipLayout(args: {
|
|
651
|
+
boxHeightPx: number | undefined;
|
|
652
|
+
mode: CalendarMode;
|
|
653
|
+
hasTime: boolean;
|
|
654
|
+
titleLineHeightPx: number;
|
|
655
|
+
timeLineHeightPx: number;
|
|
656
|
+
paddingYPx: number;
|
|
657
|
+
}): EventChipLayout;
|
|
658
|
+
/** How many month-cell chips fit in the available height. */
|
|
659
|
+
type MonthEventCapacity = {
|
|
660
|
+
/** Count when every event fits, with no overflow label. */
|
|
661
|
+
full: number;
|
|
662
|
+
/** Count that leaves room for the "+N more" label. */
|
|
663
|
+
withMore: number;
|
|
664
|
+
};
|
|
665
|
+
/**
|
|
666
|
+
* Derive how many event chips fit in a month cell from the measured space.
|
|
667
|
+
* `chipRowHeightPx` is one chip plus its gap; `moreRowHeightPx` is the overflow
|
|
668
|
+
* label plus its gap. Both counts are clamped to >= 0.
|
|
669
|
+
*/
|
|
670
|
+
declare function monthEventCapacity(availableHeightPx: number, chipRowHeightPx: number, moreRowHeightPx: number): MonthEventCapacity;
|
|
671
|
+
/**
|
|
672
|
+
* Chips to show for a day: all of them when they fit, otherwise `withMore` (at
|
|
673
|
+
* least one) so the rest collapse into a "+N more" label.
|
|
674
|
+
*/
|
|
675
|
+
declare function monthVisibleCount(total: number, capacity: MonthEventCapacity): number;
|
|
676
|
+
/** An event parsed from iCal, carrying the standard fields it also round-trips. */
|
|
677
|
+
interface ICalEvent extends ICalendarEvent {
|
|
678
|
+
/** The VEVENT `UID`, if present. */
|
|
679
|
+
uid?: string;
|
|
680
|
+
/** The VEVENT `DESCRIPTION`, if present. */
|
|
681
|
+
description?: string;
|
|
682
|
+
/** The VEVENT `LOCATION`, if present. */
|
|
683
|
+
location?: string;
|
|
684
|
+
}
|
|
685
|
+
/** Options for {@link toICalendar}. */
|
|
686
|
+
interface ToICalendarOptions {
|
|
687
|
+
/** `PRODID` written to the calendar header. Default `-//super-calendar//EN`. */
|
|
688
|
+
prodId?: string;
|
|
689
|
+
/** The `DTSTAMP` stamped on every event (when it was written). Default: now. */
|
|
690
|
+
now?: Date;
|
|
691
|
+
}
|
|
692
|
+
/**
|
|
693
|
+
* Parse an iCalendar (`.ics`) string into events. Reads every `VEVENT`; ignores
|
|
694
|
+
* VTODO/VJOURNAL/VTIMEZONE and unknown properties. Events without a usable
|
|
695
|
+
* `DTSTART` are skipped. All-day events (`VALUE=DATE`) with no `DTEND` get a
|
|
696
|
+
* one-day span.
|
|
697
|
+
*
|
|
698
|
+
* @example
|
|
699
|
+
* ```ts
|
|
700
|
+
* const events = parseICalendar(await file.text());
|
|
701
|
+
* ```
|
|
702
|
+
*/
|
|
703
|
+
declare function parseICalendar(ics: string): ICalEvent[];
|
|
704
|
+
/**
|
|
705
|
+
* Serialize events to an iCalendar (`.ics`) string. Timed events are written in
|
|
706
|
+
* UTC (`...Z`); all-day events (`allDay: true`) use `VALUE=DATE`. A `recurrence`
|
|
707
|
+
* becomes an `RRULE`, and `uid` / `description` / `location` round-trip.
|
|
708
|
+
*
|
|
709
|
+
* @example
|
|
710
|
+
* ```ts
|
|
711
|
+
* const ics = toICalendar(events);
|
|
712
|
+
* ```
|
|
713
|
+
*/
|
|
714
|
+
declare function toICalendar(events: ICalEvent[], options?: ToICalendarOptions): string;
|
|
715
|
+
/** A JSON or iCalendar URL, or a caller-owned async event loader. */
|
|
716
|
+
type EventSource<T = unknown> = string | (() => Promise<CalendarEvent<T>[]>);
|
|
717
|
+
/** Options for loading a calendar event source. */
|
|
718
|
+
interface EventSourceOptions<T> {
|
|
719
|
+
/**
|
|
720
|
+
* Feed format for URL sources: `"json"` (default) expects an array of event
|
|
721
|
+
* objects with ISO `start`/`end` strings; `"ics"` parses an iCalendar feed.
|
|
722
|
+
* URLs ending in `.ics` default to `"ics"`.
|
|
723
|
+
*/
|
|
724
|
+
format?: "json" | "ics";
|
|
725
|
+
/**
|
|
726
|
+
* Map the parsed JSON array into events, for feeds whose shape doesn't match
|
|
727
|
+
* `CalendarEvent` (rename fields, attach `resourceId`, filter). The default
|
|
728
|
+
* validates calendar fields and revives event and recurrence date strings.
|
|
729
|
+
*/
|
|
730
|
+
map?: (items: unknown[]) => CalendarEvent<T>[];
|
|
731
|
+
/** Re-fetch every N ms. Values outside (0, 2147483647] or non-finite values disable polling. */
|
|
732
|
+
refetchIntervalMs?: number;
|
|
733
|
+
}
|
|
734
|
+
/** Load one event batch. A caller can abort URL requests with signal. */
|
|
735
|
+
declare function loadEventSource<T = unknown>({ source, format, map, signal }: EventSourceOptions<T> & {
|
|
736
|
+
source: EventSource<T>;
|
|
737
|
+
signal?: AbortSignal;
|
|
738
|
+
}): Promise<CalendarEvent<T>[]>;
|
|
739
|
+
/** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
|
|
740
|
+
type PositionedEvent<T> = {
|
|
741
|
+
/** The source event for this segment. */
|
|
742
|
+
event: CalendarEvent<T>;
|
|
743
|
+
/**
|
|
744
|
+
* Clock time of the segment start on this day, in fractional hours: the
|
|
745
|
+
* time-grid row it starts in. On a DST change day this differs from the time
|
|
746
|
+
* elapsed since midnight (see {@link wallClockHours}).
|
|
747
|
+
*/
|
|
748
|
+
startHours: number;
|
|
749
|
+
/** Clock hours the segment spans on this day (clamped to a small minimum). */
|
|
750
|
+
durationHours: number;
|
|
751
|
+
/** Zero-based column index within its overlap cluster. */
|
|
752
|
+
column: number;
|
|
753
|
+
/** Total columns in this event's overlap cluster. */
|
|
754
|
+
columns: number;
|
|
755
|
+
/** True when the segment is clipped because the event continues before/after this day. */
|
|
756
|
+
continuesBefore: boolean;
|
|
757
|
+
continuesAfter: boolean;
|
|
758
|
+
};
|
|
759
|
+
/**
|
|
760
|
+
* The fractional hour `date` shows on the clock, which is the time-grid row it
|
|
761
|
+
* belongs in, clamped to `[dayStart, nextDayStart]` so the midnight that ends
|
|
762
|
+
* the day reads 24. On a DST change day this differs from the time elapsed
|
|
763
|
+
* since midnight: after clocks go back, 10:00 is 11 hours in but reads 10.
|
|
764
|
+
* Worklet-safe, so a UI-thread preview places events the same way.
|
|
765
|
+
*/
|
|
766
|
+
declare function wallClockHours(date: Date, dayStart: Date, nextDayStart: Date): number;
|
|
767
|
+
/**
|
|
768
|
+
* The hours between `from` and `to` as the clock reads them: the elapsed hours
|
|
769
|
+
* plus any DST offset change between the two, so 01:30 to 03:30 is 2 even on a
|
|
770
|
+
* spring-forward day when only 1 hour passes. In the hour a fall-back change
|
|
771
|
+
* repeats the clock can read earlier at `to` than at `from` (01:30 EDT to 01:00
|
|
772
|
+
* EST); such a span keeps its elapsed length so it still has a size to draw.
|
|
773
|
+
* Worklet-safe, so a UI-thread drag preview sizes boxes the same way.
|
|
774
|
+
*/
|
|
775
|
+
declare function clockHoursBetween(from: Date, to: Date): number;
|
|
776
|
+
/**
|
|
777
|
+
* The instant a time grid draws the bottom edge of `[start, end]` at. That is
|
|
778
|
+
* `end`, except in the hour a fall-back change repeats: a span whose clock runs
|
|
779
|
+
* backwards (01:30 EDT to 01:00 EST) is drawn its elapsed length from `start`
|
|
780
|
+
* (see {@link clockHoursBetween}), so its edge reads 02:00. Resizing from that
|
|
781
|
+
* instant keeps the edge under the pointer. Worklet-safe.
|
|
782
|
+
*/
|
|
783
|
+
declare function drawnEnd(start: Date, end: Date): Date;
|
|
784
|
+
/**
|
|
785
|
+
* Lay out a single day's events: events that overlap in time are split into
|
|
786
|
+
* side-by-side columns. Multi-day events are clipped to the portion that falls
|
|
787
|
+
* on `day` (e.g. a 23:00→01:00 event renders 23:00–24:00 on the start day and
|
|
788
|
+
* 00:00–01:00 on the next). Pure — safe to call per render, never per frame.
|
|
789
|
+
*/
|
|
790
|
+
declare function layoutDayEvents<T>(events: CalendarEvent<T>[], day: Date): PositionedEvent<T>[];
|
|
791
|
+
/**
|
|
792
|
+
* Whether an event belongs in the all-day lane. An explicit `allDay` flag wins;
|
|
793
|
+
* otherwise it's inferred when the event spans whole days (both `start` and
|
|
794
|
+
* `end` land on midnight, e.g. an iCal-style all-day event). Pure.
|
|
795
|
+
*/
|
|
796
|
+
declare function isAllDayEvent<T>(event: CalendarEvent<T>): boolean;
|
|
797
|
+
/**
|
|
798
|
+
* The `startOfDay` ISO keys of every calendar day an event touches (inclusive).
|
|
799
|
+
* An event ending exactly at midnight does not count the following day. Used to
|
|
800
|
+
* index events by day for the month grid. Pure.
|
|
801
|
+
*/
|
|
802
|
+
declare function eventDayKeys<T>(event: CalendarEvent<T>): string[];
|
|
803
|
+
/**
|
|
804
|
+
* Index events by the `startOfDay` ISO key of every day they touch (via
|
|
805
|
+
* {@link eventDayKeys}), so a month grid can look up a day's events with
|
|
806
|
+
* `startOfDay(date).toISOString()`. Built once and shared across month cells.
|
|
807
|
+
*/
|
|
808
|
+
declare function groupEventsByDay<T>(events: readonly CalendarEvent<T>[]): Map<string, CalendarEvent<T>[]>;
|
|
809
|
+
/**
|
|
810
|
+
* Order a day's events for the month and list views: all-day events come first
|
|
811
|
+
* (they head the day regardless of their start time), then timed events by start.
|
|
812
|
+
* Shared by both renderers so the order is identical. Use as an `Array.sort`
|
|
813
|
+
* comparator.
|
|
814
|
+
*/
|
|
815
|
+
declare function compareDayEvents<T>(a: CalendarEvent<T>, b: CalendarEvent<T>): number;
|
|
816
|
+
/**
|
|
817
|
+
* The closed hour-spans of a day to shade on the time grid, given a
|
|
818
|
+
* `businessHours` callback and the visible `[minHour, maxHour]` window: the spans
|
|
819
|
+
* before open and after close (clamped to the window), the whole window when the
|
|
820
|
+
* day is closed (`null`) or the open hours are inverted/empty, or none when the
|
|
821
|
+
* callback returns `undefined`. Shared by both renderers so shading stays
|
|
822
|
+
* identical. Co-located with `groupEventsByDay`; both feed the grid layout.
|
|
823
|
+
*/
|
|
824
|
+
declare function closedHourBands(day: Date, businessHours: BusinessHours | undefined, minHour?: number, maxHour?: number): {
|
|
825
|
+
start: number;
|
|
826
|
+
end: number;
|
|
827
|
+
}[];
|
|
828
|
+
/** True when the event paints as a shaded background band, not an event box. */
|
|
829
|
+
declare function isBackgroundEvent<T>(event: CalendarEvent<T>): boolean;
|
|
830
|
+
/**
|
|
831
|
+
* The background events of `events` sliced to `day`, as fractional-hour bands
|
|
832
|
+
* (an all-day or multi-day background covers the day's full window). Shared by
|
|
833
|
+
* both renderers so the shading can't disagree.
|
|
834
|
+
*/
|
|
835
|
+
declare function backgroundBandsForDay<T>(events: CalendarEvent<T>[], day: Date): {
|
|
836
|
+
event: CalendarEvent<T>;
|
|
837
|
+
startHours: number;
|
|
838
|
+
endHours: number;
|
|
839
|
+
}[];
|
|
840
|
+
/**
|
|
841
|
+
* One event's placement within a single week row of the month grid: the column
|
|
842
|
+
* span it covers and the lane (stacked row) it sits in, plus whether it continues
|
|
843
|
+
* past this row's edges (so the renderer can draw a "continues" affordance and
|
|
844
|
+
* square off the clipped end). Columns index into the row's `days` array, so with
|
|
845
|
+
* `hiddenDays` a bar spans the visible columns it touches.
|
|
846
|
+
*/
|
|
847
|
+
interface MonthEventSegment<T = unknown> {
|
|
848
|
+
event: CalendarEvent<T>;
|
|
849
|
+
/** First covered column in the row (0-based, inclusive). */
|
|
850
|
+
startCol: number;
|
|
851
|
+
/** Last covered column in the row (inclusive). */
|
|
852
|
+
endCol: number;
|
|
853
|
+
/** Stacking row within the day cells; 0 is the topmost. */
|
|
854
|
+
lane: number;
|
|
855
|
+
/** The event started before this row's first day. */
|
|
856
|
+
continuesBefore: boolean;
|
|
857
|
+
/** The event ends after this row's last day. */
|
|
858
|
+
continuesAfter: boolean;
|
|
859
|
+
}
|
|
860
|
+
/** The laid-out event segments for one week row, with the number of lanes used. */
|
|
861
|
+
interface MonthWeekEvents<T = unknown> {
|
|
862
|
+
segments: MonthEventSegment<T>[];
|
|
863
|
+
/** Highest lane index used + 1 (0 when the row has no events). */
|
|
864
|
+
laneCount: number;
|
|
865
|
+
}
|
|
866
|
+
/**
|
|
867
|
+
* Lay out one week row's events as continuous horizontal bars: each event becomes
|
|
868
|
+
* a single segment spanning the columns it covers (not a chip repeated per day),
|
|
869
|
+
* stacked into lanes so overlapping events sit on separate rows. Multi-day events
|
|
870
|
+
* that cross the row edges are marked `continuesBefore`/`continuesAfter`. Shared by
|
|
871
|
+
* both renderers so the month grid draws identical spanning bars.
|
|
872
|
+
*
|
|
873
|
+
* Column indices map into the given `days` array in whatever display order it uses,
|
|
874
|
+
* so this is order-independent: a right-to-left (reversed) week lays out correctly,
|
|
875
|
+
* and `continuesBefore`/`continuesAfter` track the array's first/last column edge
|
|
876
|
+
* (not chronology), so the clipped end is squared on the right visual side.
|
|
877
|
+
*
|
|
878
|
+
* Lanes are packed greedily after sorting by start column then longest span first,
|
|
879
|
+
* matching how calendars keep long events on the upper lanes.
|
|
880
|
+
*/
|
|
881
|
+
declare function layoutMonthWeek<T>(days: Date[], events: readonly CalendarEvent<T>[]): MonthWeekEvents<T>;
|
|
882
|
+
/** A single day in the grid, with all the state a custom cell needs to render. */
|
|
883
|
+
interface MonthGridDay {
|
|
884
|
+
/** The day this cell represents. */
|
|
885
|
+
date: Date;
|
|
886
|
+
/** Stable `yyyy-MM-dd` id, handy as a React key. */
|
|
887
|
+
id: string;
|
|
888
|
+
/** Day-of-month, e.g. "1". */
|
|
889
|
+
label: string;
|
|
890
|
+
/** False for days bleeding in from the previous or next month. */
|
|
891
|
+
isCurrentMonth: boolean;
|
|
892
|
+
/** The day is today. */
|
|
893
|
+
isToday: boolean;
|
|
894
|
+
/** The day is a Saturday or Sunday. */
|
|
895
|
+
isWeekend: boolean;
|
|
896
|
+
/** The day fails the min/max/disabled constraints. */
|
|
897
|
+
isDisabled: boolean;
|
|
898
|
+
/** The day is a `selectedDates` day or a range endpoint (and not disabled). */
|
|
899
|
+
isSelected: boolean;
|
|
900
|
+
/** The day is the range's start endpoint. */
|
|
901
|
+
isRangeStart: boolean;
|
|
902
|
+
/** The day is the range's end endpoint. */
|
|
903
|
+
isRangeEnd: boolean;
|
|
904
|
+
/** Inside a complete range (endpoints included). */
|
|
905
|
+
isInRange: boolean;
|
|
906
|
+
}
|
|
907
|
+
/** One week row. */
|
|
908
|
+
interface MonthGridWeek {
|
|
909
|
+
/** Stable id for the week row, handy as a React key. */
|
|
910
|
+
id: string;
|
|
911
|
+
/** The seven days of the row, in display order. */
|
|
912
|
+
days: MonthGridDay[];
|
|
913
|
+
}
|
|
914
|
+
/** A weekday header cell (e.g. "Mon"). */
|
|
915
|
+
interface MonthGridWeekday {
|
|
916
|
+
/** A representative date for the column, used to derive the label. */
|
|
917
|
+
date: Date;
|
|
918
|
+
/** The short weekday name (e.g. "Mon"), localised via `locale`. */
|
|
919
|
+
label: string;
|
|
920
|
+
}
|
|
921
|
+
/** The full grid for one month: the week rows and the weekday header cells. */
|
|
922
|
+
interface MonthGrid {
|
|
923
|
+
/** The week rows, padded to whole weeks. */
|
|
924
|
+
weeks: MonthGridWeek[];
|
|
925
|
+
/** The weekday header cells, in display order. */
|
|
926
|
+
weekdays: MonthGridWeekday[];
|
|
927
|
+
}
|
|
928
|
+
/**
|
|
929
|
+
* Weekday header label width: `narrow` ("M"), `short` ("Mon", the default), or
|
|
930
|
+
* `long` ("Monday").
|
|
931
|
+
*/
|
|
932
|
+
type WeekdayFormat = "narrow" | "short" | "long";
|
|
933
|
+
/**
|
|
934
|
+
* The date-fns format token for a {@link WeekdayFormat}. Exposed so a renderer
|
|
935
|
+
* that formats its own weekday header (rather than reading {@link buildMonthGrid})
|
|
936
|
+
* keeps the same mapping.
|
|
937
|
+
*/
|
|
938
|
+
declare function weekdayFormatToken(format: WeekdayFormat): string;
|
|
939
|
+
/** Options for {@link buildMonthGrid} and {@link useMonthGrid}. */
|
|
940
|
+
interface UseMonthGridOptions extends DateSelectionConstraints {
|
|
941
|
+
/** First day of the week. Sunday = 0 (default) … Saturday = 6. */
|
|
942
|
+
weekStartsOn?: WeekStartsOn;
|
|
943
|
+
/** Weekdays (0=Sunday…6=Saturday) to drop from the grid and header. */
|
|
944
|
+
hiddenDays?: number[];
|
|
945
|
+
/** Weekday header label width. Default `short` ("Mon"). */
|
|
946
|
+
weekdayFormat?: WeekdayFormat;
|
|
947
|
+
/** Always return six week rows for a fixed-height grid. Default false. */
|
|
948
|
+
showSixWeeks?: boolean;
|
|
949
|
+
/** Reverse each week's day order (right-to-left). Default false. */
|
|
950
|
+
isRTL?: boolean;
|
|
951
|
+
/** Selected discrete days (single/multiple). */
|
|
952
|
+
selectedDates?: Date[];
|
|
953
|
+
/** Selected span. */
|
|
954
|
+
selectedRange?: DateRange;
|
|
955
|
+
/** A date-fns locale for the weekday labels. */
|
|
956
|
+
locale?: Locale;
|
|
957
|
+
}
|
|
958
|
+
/**
|
|
959
|
+
* Pure month-grid builder: the weeks and weekday headers for `month`, each day
|
|
960
|
+
* annotated with selection/disabled/today state. Use this when you need the
|
|
961
|
+
* data outside React; inside a component prefer {@link useMonthGrid}.
|
|
962
|
+
*/
|
|
963
|
+
declare function buildMonthGrid(month: Date, options?: UseMonthGridOptions): MonthGrid;
|
|
964
|
+
/**
|
|
965
|
+
* Materialise recurring events into concrete occurrences overlapping
|
|
966
|
+
* `[rangeStart, rangeEnd]`. Non-recurring events pass through untouched, so the
|
|
967
|
+
* result is ready to hand to `<Calendar events={...} />`. Each occurrence keeps
|
|
968
|
+
* the original event's duration and fields (minus `recurrence`).
|
|
969
|
+
*/
|
|
970
|
+
declare function expandRecurringEvents<T>(events: CalendarEvent<T>[], rangeStart: Date, rangeEnd: Date): CalendarEvent<T>[];
|
|
971
|
+
/**
|
|
972
|
+
* Reinterpret an instant as its wall-clock time in `timeZone`, returned as a
|
|
973
|
+
* device-local `Date` whose fields (hours, minutes, …) read back as that zone's
|
|
974
|
+
* clock. The calendar lays events out from `getHours()`/`getMinutes()`, so
|
|
975
|
+
* passing zoned dates makes it render in `timeZone` regardless of the device.
|
|
976
|
+
*
|
|
977
|
+
* DST-correct via `Intl` (available on modern React Native Hermes/JSC and the
|
|
978
|
+
* web). The result is for display/layout only; it no longer points at the
|
|
979
|
+
* original UTC instant, so don't round-trip it back to a real time.
|
|
980
|
+
*/
|
|
981
|
+
declare function toZonedTime(date: Date, timeZone: string): Date;
|
|
982
|
+
/**
|
|
983
|
+
* The inverse of {@link toZonedTime}: given a wall-clock time in `timeZone`,
|
|
984
|
+
* return the absolute UTC instant. Pass the wall clock as a `Date` whose **UTC**
|
|
985
|
+
* fields hold the components (e.g. `new Date(Date.UTC(y, m, d, h, min))`). Used to
|
|
986
|
+
* resolve iCal `TZID` times; DST-correct via a two-pass offset (ambiguous
|
|
987
|
+
* fall-back times resolve to the post-transition offset).
|
|
988
|
+
*/
|
|
989
|
+
declare function zonedTimeToUtc(wallClock: Date, timeZone: string): Date;
|
|
990
|
+
/**
|
|
991
|
+
* Map every event's `start`/`end` through {@link toZonedTime} so the calendar
|
|
992
|
+
* displays them in `timeZone`. Other fields are preserved. Memoize the result
|
|
993
|
+
* (e.g. with `useMemo`) since it allocates new dates.
|
|
994
|
+
*/
|
|
995
|
+
declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
|
|
996
|
+
export { cellRangeFromDrag as $, loadEventSource as A, nextDateRange as At, eventAccessibilityLabel as B, BusinessHoursBand as Bt, groupEventsByDay as C, DateSelectionConstraints as Ct, wallClockHours as D, isDateSelectable as Dt, layoutDayEvents as E, daySelectionState as Et, EventAccessibilityLabelContext as F, rangeBandKind as Ft, monthEventCapacity as G, CreateGhostArgs as Gt, eventTimeLabel as H, CalendarEvent as Ht, EventAccessibilityLabeler as I, CalendarColors as It, titleNumberOfLines as J, RecurrenceFrequency as Jt, monthVisibleCount as K, EventKeyExtractor as Kt, EventChipLayout as L, darkColors as Lt, ToICalendarOptions as M, RangeBandKind as Mt, parseICalendar as N, bandRounding as Nt, EventSource as O, isRangeEndpoint as Ot, toICalendar as P, dayBadgeKind as Pt, resolveCalendarLabels as Q, WeekStartsOn as Qt, MIN_BOX_HEIGHT_FOR_TIME as R, lightColors as Rt, eventDayKeys as S, DateRange as St, isBackgroundEvent as T, UseDateRangeOptions as Tt, formatHour as U, CalendarHandle as Ut, eventChipLayout as V, BusinessHoursValue as Vt, isTimeVisibleAtHeight as W, CalendarMode as Wt, dayAccessibilityLabel as X, ScrollToTimeOptions as Xt, CalendarLabels as Y, RecurrenceRule as Yt, defaultCalendarLabels as Z, TimeGridMode as Zt, backgroundBandsForDay as _, isWeekend as _t, MonthEventSegment as a, overlapsOtherEvents as at, compareDayEvents as b, weekDaysCount as bt, MonthGridWeek as c, shiftMinutes as ct, UseMonthGridOptions as d, filterHiddenDays as dt, clampMoveStartMinutes as et, WeekdayFormat as f, getIsToday as ft, PositionedEvent as g, isSameCalendarDay as gt, weekdayFormatToken as h, getYearMonths as ht, expandRecurringEvents as i, movedClockSpan as it, ICalEvent as j, DayBadgeKind as jt, EventSourceOptions as k, isWithinDateRange as kt, MonthGridWeekday as l, snapDeltaMinutes as lt, layoutMonthWeek as m, getWeekDays as mt, toZonedTime as n, monthCreateRange as nt, MonthGrid as o, pageStepDays as ot, buildMonthGrid as p, getViewDays as pt, titleEllipsizeMode as q, ICalendarEvent as qt, zonedTimeToUtc as r, monthDropBounds as rt, MonthGridDay as s, resolveDraggedBounds as st, eventsInTimeZone as t, eventsOverlap as tt, MonthWeekEvents as u, buildMonthWeeks as ut, clockHoursBetween as v, minutesIntoDay as vt, isAllDayEvent as w, DaySelectionState as wt, drawnEnd as x, CalendarSelection as xt, closedHourBands as y, viewDayCount as yt, MonthEventCapacity as z, BusinessHours as zt };
|