@super-calendar/core 2.5.0 → 2.7.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/dist/index.d.mts +154 -13
- package/dist/index.d.ts +154 -13
- package/dist/index.js +248 -42
- package/dist/index.mjs +243 -44
- package/package.json +1 -1
- package/src/index.ts +2 -0
- package/src/tokens.ts +4 -0
- package/src/types.ts +50 -9
- package/src/utils/dates.ts +39 -9
- package/src/utils/drag.ts +18 -0
- package/src/utils/layout.ts +56 -8
- package/src/utils/monthGrid.ts +7 -1
- package/src/utils/recurrence.ts +16 -3
- package/src/utils/useEventSource.ts +125 -0
- package/src/utils/useNow.ts +47 -0
package/dist/index.d.mts
CHANGED
|
@@ -2,9 +2,9 @@ import { Locale } from "date-fns";
|
|
|
2
2
|
import { Dispatch, SetStateAction } from "react";
|
|
3
3
|
//#region src/types.d.ts
|
|
4
4
|
/** The view the calendar renders: a day-column grid (`day`, `3days`, `week`, `custom`), the `month` grid, or the `schedule` list. */
|
|
5
|
-
type CalendarMode = "day" | "3days" | "week" | "custom" | "month" | "schedule";
|
|
5
|
+
type CalendarMode = "day" | "3days" | "week" | "custom" | "month" | "schedule" | "year";
|
|
6
6
|
/** The time-grid modes (day-column views, excluding month and schedule). */
|
|
7
|
-
type TimeGridMode = Exclude<CalendarMode, "month" | "schedule">;
|
|
7
|
+
type TimeGridMode = Exclude<CalendarMode, "month" | "schedule" | "year">;
|
|
8
8
|
/**
|
|
9
9
|
* The minimal shape every calendar event must have. Layout (positioning,
|
|
10
10
|
* overlap resolution, paging) only ever reads `start`/`end`; `title` is used by
|
|
@@ -26,6 +26,23 @@ interface ICalendarEvent {
|
|
|
26
26
|
allDay?: boolean;
|
|
27
27
|
/** Ignore taps/long-presses on this event (the built-in renderer also dims it). */
|
|
28
28
|
disabled?: boolean;
|
|
29
|
+
/**
|
|
30
|
+
* Whether this event can be dragged to move or resize. Defaults to `true`, so
|
|
31
|
+
* enabling drag with `onDragEvent` makes every event movable. Set `false` to
|
|
32
|
+
* lock a specific event (a confirmed booking, someone else's event): it keeps
|
|
33
|
+
* its normal look and still responds to taps, it just can't be picked up. Use
|
|
34
|
+
* this for events that can *never* move; to reject a move only for certain
|
|
35
|
+
* targets (an overlap, an out-of-bounds slot), return `false` from `onDragEvent`
|
|
36
|
+
* instead so the event drags and snaps back.
|
|
37
|
+
*/
|
|
38
|
+
draggable?: boolean;
|
|
39
|
+
/**
|
|
40
|
+
* How the event renders. `"auto"` (default) is a normal event box/chip;
|
|
41
|
+
* `"background"` paints the event's time range as a non-interactive shaded
|
|
42
|
+
* band behind the grid instead (blocked time, holidays). Background events
|
|
43
|
+
* are excluded from chips, the agenda, and year-view dots.
|
|
44
|
+
*/
|
|
45
|
+
display?: "auto" | "background";
|
|
29
46
|
/**
|
|
30
47
|
* Repeat rule. Pass the event to `expandRecurringEvents(events, start, end)` to
|
|
31
48
|
* materialise its occurrences within a range; the calendar itself doesn't
|
|
@@ -75,8 +92,11 @@ interface RecurrenceRule {
|
|
|
75
92
|
*/
|
|
76
93
|
months?: number[];
|
|
77
94
|
/**
|
|
78
|
-
* Dates to skip (exceptions)
|
|
79
|
-
*
|
|
95
|
+
* Dates to skip (exceptions), dropped by `expandRecurringEvents`. A date at
|
|
96
|
+
* local midnight drops every occurrence on that calendar day (iCal
|
|
97
|
+
* `EXDATE;VALUE=DATE`); a date with a time drops only the occurrence starting
|
|
98
|
+
* at that exact instant. Corollary: an occurrence that itself starts at
|
|
99
|
+
* midnight can only be excluded day-wide. Maps to iCal `EXDATE`.
|
|
80
100
|
*/
|
|
81
101
|
exdates?: Date[];
|
|
82
102
|
/**
|
|
@@ -97,15 +117,35 @@ type EventKeyExtractor<T = unknown> = (event: CalendarEvent<T>, index: number) =
|
|
|
97
117
|
/** Sunday = 0 … Saturday = 6, matching `Date.prototype.getDay()`. */
|
|
98
118
|
type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
|
|
99
119
|
/**
|
|
100
|
-
* A day's open hours for `businessHours` shading
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
120
|
+
* A day's open hours for `businessHours` shading, as hours (fractions allowed,
|
|
121
|
+
* e.g. `9.5`): a single window `{ start, end }`, or an array of windows to leave
|
|
122
|
+
* a closed gap between them (a lunch break: `[{ start: 9, end: 12 }, { start: 13,
|
|
123
|
+
* end: 17 }]`). Everything outside the window(s) is shaded closed.
|
|
104
124
|
*/
|
|
105
|
-
type
|
|
125
|
+
type BusinessHoursValue = {
|
|
106
126
|
start: number;
|
|
107
127
|
end: number;
|
|
108
|
-
} |
|
|
128
|
+
} | {
|
|
129
|
+
start: number;
|
|
130
|
+
end: number;
|
|
131
|
+
}[] | null;
|
|
132
|
+
/**
|
|
133
|
+
* The `businessHours` callback: return the open hours for `date` (see
|
|
134
|
+
* {@link BusinessHoursValue}), `null` when the day is fully closed (all shaded),
|
|
135
|
+
* or `undefined` for no business-hours shading. Shared by both renderers; pair
|
|
136
|
+
* with `closedHourBands` to get the spans to shade.
|
|
137
|
+
*/
|
|
138
|
+
type BusinessHours = (date: Date) => BusinessHoursValue;
|
|
139
|
+
/**
|
|
140
|
+
* One closed-hours band handed to a `renderBusinessHours` override: the day it
|
|
141
|
+
* belongs to and its span as fractional hours, already clamped to the visible
|
|
142
|
+
* window. `ResourceTimeline` extends it with the lane's resource.
|
|
143
|
+
*/
|
|
144
|
+
interface BusinessHoursBand {
|
|
145
|
+
date: Date;
|
|
146
|
+
start: number;
|
|
147
|
+
end: number;
|
|
148
|
+
}
|
|
109
149
|
//#endregion
|
|
110
150
|
//#region src/tokens.d.ts
|
|
111
151
|
/** The shared colour palette both renderers derive their themes from. */
|
|
@@ -142,6 +182,8 @@ interface CalendarColors {
|
|
|
142
182
|
eventBackground: string;
|
|
143
183
|
/** Default event chip text. */
|
|
144
184
|
eventText: string;
|
|
185
|
+
/** Shaded band behind a `display: "background"` event. */
|
|
186
|
+
backgroundEvent: string;
|
|
145
187
|
}
|
|
146
188
|
/** The default light-theme colour palette. */
|
|
147
189
|
declare const lightColors: CalendarColors;
|
|
@@ -293,16 +335,23 @@ declare const weekDaysCount: (weekStartsOn: WeekStartsOn, weekEndsOn: WeekStarts
|
|
|
293
335
|
* from `weekStartsOn` to `weekEndsOn` (anchored to `date`'s week, paging by week);
|
|
294
336
|
* otherwise every mode shows `viewDayCount` consecutive days starting at `date`.
|
|
295
337
|
*/
|
|
296
|
-
declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn) => Date[];
|
|
338
|
+
declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn, hiddenDays?: number[]) => Date[];
|
|
297
339
|
/**
|
|
298
340
|
* The calendar weeks covering `month`, padded to whole weeks starting on
|
|
299
341
|
* `weekStartsOn`. `showSixWeeks` always returns six rows (42 days) for a
|
|
300
342
|
* fixed-height grid; `isRTL` reverses each week's day order.
|
|
301
343
|
*/
|
|
302
|
-
declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, { showSixWeeks, isRTL }?: {
|
|
344
|
+
declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, { showSixWeeks, isRTL, hiddenDays }?: {
|
|
303
345
|
showSixWeeks?: boolean;
|
|
304
346
|
isRTL?: boolean;
|
|
347
|
+
hiddenDays?: number[];
|
|
305
348
|
}) => Date[][];
|
|
349
|
+
/**
|
|
350
|
+
* Drop the days whose weekday (0=Sunday…6=Saturday) is listed in `hiddenDays`.
|
|
351
|
+
* Hiding all seven weekdays is treated as hiding nothing (matching
|
|
352
|
+
* `getViewDays`), so a misconfiguration degrades to the full grid, not a blank.
|
|
353
|
+
*/
|
|
354
|
+
declare const filterHiddenDays: (days: Date[], hiddenDays?: number[]) => Date[];
|
|
306
355
|
/** True when `date` is a Saturday or Sunday. */
|
|
307
356
|
declare const isWeekend: (date: Date) => boolean;
|
|
308
357
|
/** True when `date` falls on the current calendar day. */
|
|
@@ -311,8 +360,17 @@ declare const getIsToday: (date: Date) => boolean;
|
|
|
311
360
|
declare const isSameCalendarDay: (a: Date, b: Date) => boolean;
|
|
312
361
|
/** Minutes elapsed since midnight (0–1439). */
|
|
313
362
|
declare const minutesIntoDay: (date: Date) => number;
|
|
363
|
+
/** The twelve month anchors (first-of-month) of `date`'s year, January first. */
|
|
364
|
+
declare const getYearMonths: (date: Date) => Date[];
|
|
314
365
|
//#endregion
|
|
315
366
|
//#region src/utils/drag.d.ts
|
|
367
|
+
/**
|
|
368
|
+
* How many calendar days one time-grid page spans, used to advance the view by a
|
|
369
|
+
* whole page (e.g. when dragging an event past the edge into the next week).
|
|
370
|
+
* Deliberately ignores `hiddenDays` so a week always steps 7, matching the
|
|
371
|
+
* keyboard PageUp/PageDown paging and `Calendar`'s own page step.
|
|
372
|
+
*/
|
|
373
|
+
declare function pageStepDays(mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number): number;
|
|
316
374
|
/**
|
|
317
375
|
* Minutes to shift an event, snapping a vertical pixel drag to the nearest
|
|
318
376
|
* `stepMinutes`. Runs on the UI thread inside the drag gesture. Returns 0 for a
|
|
@@ -518,6 +576,75 @@ declare function parseICalendar(ics: string): ICalEvent[];
|
|
|
518
576
|
*/
|
|
519
577
|
declare function toICalendar(events: ICalEvent[], options?: ToICalendarOptions): string;
|
|
520
578
|
//#endregion
|
|
579
|
+
//#region src/utils/useNow.d.ts
|
|
580
|
+
/** Options for {@link useNow}. */
|
|
581
|
+
interface UseNowOptions {
|
|
582
|
+
/**
|
|
583
|
+
* A fixed instant to use instead of the device clock (a server-synced clock,
|
|
584
|
+
* or a stable value for tests). A fixed instant doesn't tick.
|
|
585
|
+
*/
|
|
586
|
+
now?: Date;
|
|
587
|
+
/**
|
|
588
|
+
* Shift the instant into this IANA time zone's wall-clock (the same shift
|
|
589
|
+
* `eventsInTimeZone` applies), so the now indicator lines up with events
|
|
590
|
+
* displayed in that zone rather than the device's.
|
|
591
|
+
*/
|
|
592
|
+
timeZone?: string;
|
|
593
|
+
/** Tick interval in ms (default one minute). */
|
|
594
|
+
tickMs?: number;
|
|
595
|
+
}
|
|
596
|
+
/**
|
|
597
|
+
* The current wall-clock time, re-read every `tickMs` while `enabled`, shifted
|
|
598
|
+
* into `timeZone` when given, or pinned to a fixed `now` override. Drives the
|
|
599
|
+
* now indicator on both renderers so it can't disagree with zone-shifted events.
|
|
600
|
+
*/
|
|
601
|
+
declare function useNow(enabled: boolean, { now, timeZone, tickMs }?: UseNowOptions): Date;
|
|
602
|
+
//#endregion
|
|
603
|
+
//#region src/utils/useEventSource.d.ts
|
|
604
|
+
/** Options for {@link useEventSource}. */
|
|
605
|
+
interface EventSourceOptions<T> {
|
|
606
|
+
/**
|
|
607
|
+
* Feed format for URL sources: `"json"` (default) expects an array of event
|
|
608
|
+
* objects with ISO `start`/`end` strings; `"ics"` parses an iCalendar feed.
|
|
609
|
+
* URLs ending in `.ics` default to `"ics"`.
|
|
610
|
+
*/
|
|
611
|
+
format?: "json" | "ics";
|
|
612
|
+
/**
|
|
613
|
+
* Map the parsed JSON array into events, for feeds whose shape doesn't match
|
|
614
|
+
* `CalendarEvent` (rename fields, attach `resourceId`, filter). The default
|
|
615
|
+
* revives `start`/`end` ISO strings on each item.
|
|
616
|
+
*/
|
|
617
|
+
map?: (items: unknown[]) => CalendarEvent<T>[];
|
|
618
|
+
/** Re-fetch every N ms (a live feed). Omit to fetch once. */
|
|
619
|
+
refetchIntervalMs?: number;
|
|
620
|
+
}
|
|
621
|
+
/** What {@link useEventSource} returns. */
|
|
622
|
+
interface EventSourceState<T> {
|
|
623
|
+
/** The fetched events; the previous batch is kept while a refetch runs or fails. */
|
|
624
|
+
events: CalendarEvent<T>[];
|
|
625
|
+
/** True while the first fetch (or a manual refetch) is in flight. */
|
|
626
|
+
loading: boolean;
|
|
627
|
+
/** The last fetch error, or null. Events keep their previous value on error. */
|
|
628
|
+
error: Error | null;
|
|
629
|
+
/** Fetch the source again now. */
|
|
630
|
+
refetch: () => Promise<void>;
|
|
631
|
+
}
|
|
632
|
+
/**
|
|
633
|
+
* Load events from a refreshable source: a JSON feed URL, an iCalendar feed
|
|
634
|
+
* URL, or your own async function. The hook owns fetching, optional interval
|
|
635
|
+
* refetching, and loading/error state; hand the returned `events` to any view.
|
|
636
|
+
*
|
|
637
|
+
* @example
|
|
638
|
+
* ```tsx
|
|
639
|
+
* const { events, loading, refetch } = useEventSource(
|
|
640
|
+
* "https://example.com/feed.ics",
|
|
641
|
+
* { refetchIntervalMs: 5 * 60_000 },
|
|
642
|
+
* );
|
|
643
|
+
* <Calendar mode="week" date={date} events={events} onChangeDate={setDate} />;
|
|
644
|
+
* ```
|
|
645
|
+
*/
|
|
646
|
+
declare function useEventSource<T = unknown>(source: string | (() => Promise<CalendarEvent<T>[]>), { format, map, refetchIntervalMs }?: EventSourceOptions<T>): EventSourceState<T>;
|
|
647
|
+
//#endregion
|
|
521
648
|
//#region src/utils/layout.d.ts
|
|
522
649
|
/** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
|
|
523
650
|
type PositionedEvent<T> = {
|
|
@@ -579,6 +706,18 @@ declare function closedHourBands(day: Date, businessHours: BusinessHours | undef
|
|
|
579
706
|
start: number;
|
|
580
707
|
end: number;
|
|
581
708
|
}[];
|
|
709
|
+
/** True when the event paints as a shaded background band, not an event box. */
|
|
710
|
+
declare function isBackgroundEvent<T>(event: CalendarEvent<T>): boolean;
|
|
711
|
+
/**
|
|
712
|
+
* The background events of `events` sliced to `day`, as fractional-hour bands
|
|
713
|
+
* (an all-day or multi-day background covers the day's full window). Shared by
|
|
714
|
+
* both renderers so the shading can't disagree.
|
|
715
|
+
*/
|
|
716
|
+
declare function backgroundBandsForDay<T>(events: CalendarEvent<T>[], day: Date): {
|
|
717
|
+
event: CalendarEvent<T>;
|
|
718
|
+
startHours: number;
|
|
719
|
+
endHours: number;
|
|
720
|
+
}[];
|
|
582
721
|
//#endregion
|
|
583
722
|
//#region src/utils/monthGrid.d.ts
|
|
584
723
|
/** A single day in the grid, with all the state a custom cell needs to render. */
|
|
@@ -642,6 +781,8 @@ declare function weekdayFormatToken(format: WeekdayFormat): string;
|
|
|
642
781
|
interface UseMonthGridOptions extends DateSelectionConstraints {
|
|
643
782
|
/** First day of the week. Sunday = 0 (default) … Saturday = 6. */
|
|
644
783
|
weekStartsOn?: WeekStartsOn;
|
|
784
|
+
/** Weekdays (0=Sunday…6=Saturday) to drop from the grid and header. */
|
|
785
|
+
hiddenDays?: number[];
|
|
645
786
|
/** Weekday header label width. Default `short` ("Mon"). */
|
|
646
787
|
weekdayFormat?: WeekdayFormat;
|
|
647
788
|
/** Always return six week rows for a fixed-height grid. Default false. */
|
|
@@ -709,4 +850,4 @@ declare function zonedTimeToUtc(wallClock: Date, timeZone: string): Date;
|
|
|
709
850
|
*/
|
|
710
851
|
declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
|
|
711
852
|
//#endregion
|
|
712
|
-
export { BusinessHours, CalendarColors, CalendarEvent, CalendarMode, CalendarSelection, CalendarSelectionProvider, DateRange, DateSelectionConstraints, DayBadgeKind, DaySelectionState, EventAccessibilityLabelContext, EventAccessibilityLabeler, EventChipLayout, EventKeyExtractor, ICalEvent, ICalendarEvent, MIN_BOX_HEIGHT_FOR_TIME, MonthEventCapacity, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RangeBandKind, RecurrenceFrequency, RecurrenceRule, TimeGridMode, ToICalendarOptions, UseDateRangeOptions, UseDateRangeResult, UseMonthGridOptions, WeekStartsOn, WeekdayFormat, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, formatHour, getIsToday, getViewDays, getWeekDays, groupEventsByDay, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, parseICalendar, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toICalendar, toZonedTime, useCalendarSelection, useDateRange, useMonthGrid, viewDayCount, weekDaysCount, weekdayFormatToken, zonedTimeToUtc };
|
|
853
|
+
export { BusinessHours, BusinessHoursBand, BusinessHoursValue, CalendarColors, CalendarEvent, CalendarMode, CalendarSelection, CalendarSelectionProvider, DateRange, DateSelectionConstraints, DayBadgeKind, DaySelectionState, EventAccessibilityLabelContext, EventAccessibilityLabeler, EventChipLayout, EventKeyExtractor, EventSourceOptions, EventSourceState, ICalEvent, ICalendarEvent, MIN_BOX_HEIGHT_FOR_TIME, MonthEventCapacity, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RangeBandKind, RecurrenceFrequency, RecurrenceRule, TimeGridMode, ToICalendarOptions, UseDateRangeOptions, UseDateRangeResult, UseMonthGridOptions, UseNowOptions, WeekStartsOn, WeekdayFormat, backgroundBandsForDay, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, filterHiddenDays, formatHour, getIsToday, getViewDays, getWeekDays, getYearMonths, groupEventsByDay, isAllDayEvent, isBackgroundEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, pageStepDays, parseICalendar, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toICalendar, toZonedTime, useCalendarSelection, useDateRange, useEventSource, useMonthGrid, useNow, viewDayCount, weekDaysCount, weekdayFormatToken, zonedTimeToUtc };
|
package/dist/index.d.ts
CHANGED
|
@@ -2,9 +2,9 @@ import { Dispatch, SetStateAction } from "react";
|
|
|
2
2
|
import { Locale } from "date-fns";
|
|
3
3
|
//#region src/types.d.ts
|
|
4
4
|
/** The view the calendar renders: a day-column grid (`day`, `3days`, `week`, `custom`), the `month` grid, or the `schedule` list. */
|
|
5
|
-
type CalendarMode = "day" | "3days" | "week" | "custom" | "month" | "schedule";
|
|
5
|
+
type CalendarMode = "day" | "3days" | "week" | "custom" | "month" | "schedule" | "year";
|
|
6
6
|
/** The time-grid modes (day-column views, excluding month and schedule). */
|
|
7
|
-
type TimeGridMode = Exclude<CalendarMode, "month" | "schedule">;
|
|
7
|
+
type TimeGridMode = Exclude<CalendarMode, "month" | "schedule" | "year">;
|
|
8
8
|
/**
|
|
9
9
|
* The minimal shape every calendar event must have. Layout (positioning,
|
|
10
10
|
* overlap resolution, paging) only ever reads `start`/`end`; `title` is used by
|
|
@@ -26,6 +26,23 @@ interface ICalendarEvent {
|
|
|
26
26
|
allDay?: boolean;
|
|
27
27
|
/** Ignore taps/long-presses on this event (the built-in renderer also dims it). */
|
|
28
28
|
disabled?: boolean;
|
|
29
|
+
/**
|
|
30
|
+
* Whether this event can be dragged to move or resize. Defaults to `true`, so
|
|
31
|
+
* enabling drag with `onDragEvent` makes every event movable. Set `false` to
|
|
32
|
+
* lock a specific event (a confirmed booking, someone else's event): it keeps
|
|
33
|
+
* its normal look and still responds to taps, it just can't be picked up. Use
|
|
34
|
+
* this for events that can *never* move; to reject a move only for certain
|
|
35
|
+
* targets (an overlap, an out-of-bounds slot), return `false` from `onDragEvent`
|
|
36
|
+
* instead so the event drags and snaps back.
|
|
37
|
+
*/
|
|
38
|
+
draggable?: boolean;
|
|
39
|
+
/**
|
|
40
|
+
* How the event renders. `"auto"` (default) is a normal event box/chip;
|
|
41
|
+
* `"background"` paints the event's time range as a non-interactive shaded
|
|
42
|
+
* band behind the grid instead (blocked time, holidays). Background events
|
|
43
|
+
* are excluded from chips, the agenda, and year-view dots.
|
|
44
|
+
*/
|
|
45
|
+
display?: "auto" | "background";
|
|
29
46
|
/**
|
|
30
47
|
* Repeat rule. Pass the event to `expandRecurringEvents(events, start, end)` to
|
|
31
48
|
* materialise its occurrences within a range; the calendar itself doesn't
|
|
@@ -75,8 +92,11 @@ interface RecurrenceRule {
|
|
|
75
92
|
*/
|
|
76
93
|
months?: number[];
|
|
77
94
|
/**
|
|
78
|
-
* Dates to skip (exceptions)
|
|
79
|
-
*
|
|
95
|
+
* Dates to skip (exceptions), dropped by `expandRecurringEvents`. A date at
|
|
96
|
+
* local midnight drops every occurrence on that calendar day (iCal
|
|
97
|
+
* `EXDATE;VALUE=DATE`); a date with a time drops only the occurrence starting
|
|
98
|
+
* at that exact instant. Corollary: an occurrence that itself starts at
|
|
99
|
+
* midnight can only be excluded day-wide. Maps to iCal `EXDATE`.
|
|
80
100
|
*/
|
|
81
101
|
exdates?: Date[];
|
|
82
102
|
/**
|
|
@@ -97,15 +117,35 @@ type EventKeyExtractor<T = unknown> = (event: CalendarEvent<T>, index: number) =
|
|
|
97
117
|
/** Sunday = 0 … Saturday = 6, matching `Date.prototype.getDay()`. */
|
|
98
118
|
type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
|
|
99
119
|
/**
|
|
100
|
-
* A day's open hours for `businessHours` shading
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
120
|
+
* A day's open hours for `businessHours` shading, as hours (fractions allowed,
|
|
121
|
+
* e.g. `9.5`): a single window `{ start, end }`, or an array of windows to leave
|
|
122
|
+
* a closed gap between them (a lunch break: `[{ start: 9, end: 12 }, { start: 13,
|
|
123
|
+
* end: 17 }]`). Everything outside the window(s) is shaded closed.
|
|
104
124
|
*/
|
|
105
|
-
type
|
|
125
|
+
type BusinessHoursValue = {
|
|
106
126
|
start: number;
|
|
107
127
|
end: number;
|
|
108
|
-
} |
|
|
128
|
+
} | {
|
|
129
|
+
start: number;
|
|
130
|
+
end: number;
|
|
131
|
+
}[] | null;
|
|
132
|
+
/**
|
|
133
|
+
* The `businessHours` callback: return the open hours for `date` (see
|
|
134
|
+
* {@link BusinessHoursValue}), `null` when the day is fully closed (all shaded),
|
|
135
|
+
* or `undefined` for no business-hours shading. Shared by both renderers; pair
|
|
136
|
+
* with `closedHourBands` to get the spans to shade.
|
|
137
|
+
*/
|
|
138
|
+
type BusinessHours = (date: Date) => BusinessHoursValue;
|
|
139
|
+
/**
|
|
140
|
+
* One closed-hours band handed to a `renderBusinessHours` override: the day it
|
|
141
|
+
* belongs to and its span as fractional hours, already clamped to the visible
|
|
142
|
+
* window. `ResourceTimeline` extends it with the lane's resource.
|
|
143
|
+
*/
|
|
144
|
+
interface BusinessHoursBand {
|
|
145
|
+
date: Date;
|
|
146
|
+
start: number;
|
|
147
|
+
end: number;
|
|
148
|
+
}
|
|
109
149
|
//#endregion
|
|
110
150
|
//#region src/tokens.d.ts
|
|
111
151
|
/** The shared colour palette both renderers derive their themes from. */
|
|
@@ -142,6 +182,8 @@ interface CalendarColors {
|
|
|
142
182
|
eventBackground: string;
|
|
143
183
|
/** Default event chip text. */
|
|
144
184
|
eventText: string;
|
|
185
|
+
/** Shaded band behind a `display: "background"` event. */
|
|
186
|
+
backgroundEvent: string;
|
|
145
187
|
}
|
|
146
188
|
/** The default light-theme colour palette. */
|
|
147
189
|
declare const lightColors: CalendarColors;
|
|
@@ -293,16 +335,23 @@ declare const weekDaysCount: (weekStartsOn: WeekStartsOn, weekEndsOn: WeekStarts
|
|
|
293
335
|
* from `weekStartsOn` to `weekEndsOn` (anchored to `date`'s week, paging by week);
|
|
294
336
|
* otherwise every mode shows `viewDayCount` consecutive days starting at `date`.
|
|
295
337
|
*/
|
|
296
|
-
declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn) => Date[];
|
|
338
|
+
declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn, hiddenDays?: number[]) => Date[];
|
|
297
339
|
/**
|
|
298
340
|
* The calendar weeks covering `month`, padded to whole weeks starting on
|
|
299
341
|
* `weekStartsOn`. `showSixWeeks` always returns six rows (42 days) for a
|
|
300
342
|
* fixed-height grid; `isRTL` reverses each week's day order.
|
|
301
343
|
*/
|
|
302
|
-
declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, { showSixWeeks, isRTL }?: {
|
|
344
|
+
declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, { showSixWeeks, isRTL, hiddenDays }?: {
|
|
303
345
|
showSixWeeks?: boolean;
|
|
304
346
|
isRTL?: boolean;
|
|
347
|
+
hiddenDays?: number[];
|
|
305
348
|
}) => Date[][];
|
|
349
|
+
/**
|
|
350
|
+
* Drop the days whose weekday (0=Sunday…6=Saturday) is listed in `hiddenDays`.
|
|
351
|
+
* Hiding all seven weekdays is treated as hiding nothing (matching
|
|
352
|
+
* `getViewDays`), so a misconfiguration degrades to the full grid, not a blank.
|
|
353
|
+
*/
|
|
354
|
+
declare const filterHiddenDays: (days: Date[], hiddenDays?: number[]) => Date[];
|
|
306
355
|
/** True when `date` is a Saturday or Sunday. */
|
|
307
356
|
declare const isWeekend: (date: Date) => boolean;
|
|
308
357
|
/** True when `date` falls on the current calendar day. */
|
|
@@ -311,8 +360,17 @@ declare const getIsToday: (date: Date) => boolean;
|
|
|
311
360
|
declare const isSameCalendarDay: (a: Date, b: Date) => boolean;
|
|
312
361
|
/** Minutes elapsed since midnight (0–1439). */
|
|
313
362
|
declare const minutesIntoDay: (date: Date) => number;
|
|
363
|
+
/** The twelve month anchors (first-of-month) of `date`'s year, January first. */
|
|
364
|
+
declare const getYearMonths: (date: Date) => Date[];
|
|
314
365
|
//#endregion
|
|
315
366
|
//#region src/utils/drag.d.ts
|
|
367
|
+
/**
|
|
368
|
+
* How many calendar days one time-grid page spans, used to advance the view by a
|
|
369
|
+
* whole page (e.g. when dragging an event past the edge into the next week).
|
|
370
|
+
* Deliberately ignores `hiddenDays` so a week always steps 7, matching the
|
|
371
|
+
* keyboard PageUp/PageDown paging and `Calendar`'s own page step.
|
|
372
|
+
*/
|
|
373
|
+
declare function pageStepDays(mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number): number;
|
|
316
374
|
/**
|
|
317
375
|
* Minutes to shift an event, snapping a vertical pixel drag to the nearest
|
|
318
376
|
* `stepMinutes`. Runs on the UI thread inside the drag gesture. Returns 0 for a
|
|
@@ -518,6 +576,75 @@ declare function parseICalendar(ics: string): ICalEvent[];
|
|
|
518
576
|
*/
|
|
519
577
|
declare function toICalendar(events: ICalEvent[], options?: ToICalendarOptions): string;
|
|
520
578
|
//#endregion
|
|
579
|
+
//#region src/utils/useNow.d.ts
|
|
580
|
+
/** Options for {@link useNow}. */
|
|
581
|
+
interface UseNowOptions {
|
|
582
|
+
/**
|
|
583
|
+
* A fixed instant to use instead of the device clock (a server-synced clock,
|
|
584
|
+
* or a stable value for tests). A fixed instant doesn't tick.
|
|
585
|
+
*/
|
|
586
|
+
now?: Date;
|
|
587
|
+
/**
|
|
588
|
+
* Shift the instant into this IANA time zone's wall-clock (the same shift
|
|
589
|
+
* `eventsInTimeZone` applies), so the now indicator lines up with events
|
|
590
|
+
* displayed in that zone rather than the device's.
|
|
591
|
+
*/
|
|
592
|
+
timeZone?: string;
|
|
593
|
+
/** Tick interval in ms (default one minute). */
|
|
594
|
+
tickMs?: number;
|
|
595
|
+
}
|
|
596
|
+
/**
|
|
597
|
+
* The current wall-clock time, re-read every `tickMs` while `enabled`, shifted
|
|
598
|
+
* into `timeZone` when given, or pinned to a fixed `now` override. Drives the
|
|
599
|
+
* now indicator on both renderers so it can't disagree with zone-shifted events.
|
|
600
|
+
*/
|
|
601
|
+
declare function useNow(enabled: boolean, { now, timeZone, tickMs }?: UseNowOptions): Date;
|
|
602
|
+
//#endregion
|
|
603
|
+
//#region src/utils/useEventSource.d.ts
|
|
604
|
+
/** Options for {@link useEventSource}. */
|
|
605
|
+
interface EventSourceOptions<T> {
|
|
606
|
+
/**
|
|
607
|
+
* Feed format for URL sources: `"json"` (default) expects an array of event
|
|
608
|
+
* objects with ISO `start`/`end` strings; `"ics"` parses an iCalendar feed.
|
|
609
|
+
* URLs ending in `.ics` default to `"ics"`.
|
|
610
|
+
*/
|
|
611
|
+
format?: "json" | "ics";
|
|
612
|
+
/**
|
|
613
|
+
* Map the parsed JSON array into events, for feeds whose shape doesn't match
|
|
614
|
+
* `CalendarEvent` (rename fields, attach `resourceId`, filter). The default
|
|
615
|
+
* revives `start`/`end` ISO strings on each item.
|
|
616
|
+
*/
|
|
617
|
+
map?: (items: unknown[]) => CalendarEvent<T>[];
|
|
618
|
+
/** Re-fetch every N ms (a live feed). Omit to fetch once. */
|
|
619
|
+
refetchIntervalMs?: number;
|
|
620
|
+
}
|
|
621
|
+
/** What {@link useEventSource} returns. */
|
|
622
|
+
interface EventSourceState<T> {
|
|
623
|
+
/** The fetched events; the previous batch is kept while a refetch runs or fails. */
|
|
624
|
+
events: CalendarEvent<T>[];
|
|
625
|
+
/** True while the first fetch (or a manual refetch) is in flight. */
|
|
626
|
+
loading: boolean;
|
|
627
|
+
/** The last fetch error, or null. Events keep their previous value on error. */
|
|
628
|
+
error: Error | null;
|
|
629
|
+
/** Fetch the source again now. */
|
|
630
|
+
refetch: () => Promise<void>;
|
|
631
|
+
}
|
|
632
|
+
/**
|
|
633
|
+
* Load events from a refreshable source: a JSON feed URL, an iCalendar feed
|
|
634
|
+
* URL, or your own async function. The hook owns fetching, optional interval
|
|
635
|
+
* refetching, and loading/error state; hand the returned `events` to any view.
|
|
636
|
+
*
|
|
637
|
+
* @example
|
|
638
|
+
* ```tsx
|
|
639
|
+
* const { events, loading, refetch } = useEventSource(
|
|
640
|
+
* "https://example.com/feed.ics",
|
|
641
|
+
* { refetchIntervalMs: 5 * 60_000 },
|
|
642
|
+
* );
|
|
643
|
+
* <Calendar mode="week" date={date} events={events} onChangeDate={setDate} />;
|
|
644
|
+
* ```
|
|
645
|
+
*/
|
|
646
|
+
declare function useEventSource<T = unknown>(source: string | (() => Promise<CalendarEvent<T>[]>), { format, map, refetchIntervalMs }?: EventSourceOptions<T>): EventSourceState<T>;
|
|
647
|
+
//#endregion
|
|
521
648
|
//#region src/utils/layout.d.ts
|
|
522
649
|
/** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
|
|
523
650
|
type PositionedEvent<T> = {
|
|
@@ -579,6 +706,18 @@ declare function closedHourBands(day: Date, businessHours: BusinessHours | undef
|
|
|
579
706
|
start: number;
|
|
580
707
|
end: number;
|
|
581
708
|
}[];
|
|
709
|
+
/** True when the event paints as a shaded background band, not an event box. */
|
|
710
|
+
declare function isBackgroundEvent<T>(event: CalendarEvent<T>): boolean;
|
|
711
|
+
/**
|
|
712
|
+
* The background events of `events` sliced to `day`, as fractional-hour bands
|
|
713
|
+
* (an all-day or multi-day background covers the day's full window). Shared by
|
|
714
|
+
* both renderers so the shading can't disagree.
|
|
715
|
+
*/
|
|
716
|
+
declare function backgroundBandsForDay<T>(events: CalendarEvent<T>[], day: Date): {
|
|
717
|
+
event: CalendarEvent<T>;
|
|
718
|
+
startHours: number;
|
|
719
|
+
endHours: number;
|
|
720
|
+
}[];
|
|
582
721
|
//#endregion
|
|
583
722
|
//#region src/utils/monthGrid.d.ts
|
|
584
723
|
/** A single day in the grid, with all the state a custom cell needs to render. */
|
|
@@ -642,6 +781,8 @@ declare function weekdayFormatToken(format: WeekdayFormat): string;
|
|
|
642
781
|
interface UseMonthGridOptions extends DateSelectionConstraints {
|
|
643
782
|
/** First day of the week. Sunday = 0 (default) … Saturday = 6. */
|
|
644
783
|
weekStartsOn?: WeekStartsOn;
|
|
784
|
+
/** Weekdays (0=Sunday…6=Saturday) to drop from the grid and header. */
|
|
785
|
+
hiddenDays?: number[];
|
|
645
786
|
/** Weekday header label width. Default `short` ("Mon"). */
|
|
646
787
|
weekdayFormat?: WeekdayFormat;
|
|
647
788
|
/** Always return six week rows for a fixed-height grid. Default false. */
|
|
@@ -709,4 +850,4 @@ declare function zonedTimeToUtc(wallClock: Date, timeZone: string): Date;
|
|
|
709
850
|
*/
|
|
710
851
|
declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
|
|
711
852
|
//#endregion
|
|
712
|
-
export { BusinessHours, CalendarColors, CalendarEvent, CalendarMode, CalendarSelection, CalendarSelectionProvider, DateRange, DateSelectionConstraints, DayBadgeKind, DaySelectionState, EventAccessibilityLabelContext, EventAccessibilityLabeler, EventChipLayout, EventKeyExtractor, ICalEvent, ICalendarEvent, MIN_BOX_HEIGHT_FOR_TIME, MonthEventCapacity, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RangeBandKind, RecurrenceFrequency, RecurrenceRule, TimeGridMode, ToICalendarOptions, UseDateRangeOptions, UseDateRangeResult, UseMonthGridOptions, WeekStartsOn, WeekdayFormat, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, formatHour, getIsToday, getViewDays, getWeekDays, groupEventsByDay, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, parseICalendar, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toICalendar, toZonedTime, useCalendarSelection, useDateRange, useMonthGrid, viewDayCount, weekDaysCount, weekdayFormatToken, zonedTimeToUtc };
|
|
853
|
+
export { BusinessHours, BusinessHoursBand, BusinessHoursValue, CalendarColors, CalendarEvent, CalendarMode, CalendarSelection, CalendarSelectionProvider, DateRange, DateSelectionConstraints, DayBadgeKind, DaySelectionState, EventAccessibilityLabelContext, EventAccessibilityLabeler, EventChipLayout, EventKeyExtractor, EventSourceOptions, EventSourceState, ICalEvent, ICalendarEvent, MIN_BOX_HEIGHT_FOR_TIME, MonthEventCapacity, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RangeBandKind, RecurrenceFrequency, RecurrenceRule, TimeGridMode, ToICalendarOptions, UseDateRangeOptions, UseDateRangeResult, UseMonthGridOptions, UseNowOptions, WeekStartsOn, WeekdayFormat, backgroundBandsForDay, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, filterHiddenDays, formatHour, getIsToday, getViewDays, getWeekDays, getYearMonths, groupEventsByDay, isAllDayEvent, isBackgroundEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, pageStepDays, parseICalendar, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toICalendar, toZonedTime, useCalendarSelection, useDateRange, useEventSource, useMonthGrid, useNow, viewDayCount, weekDaysCount, weekdayFormatToken, zonedTimeToUtc };
|