@super-calendar/core 2.6.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 +150 -11
- package/dist/index.d.ts +150 -11
- package/dist/index.js +245 -42
- package/dist/index.mjs +241 -44
- package/package.json +1 -1
- package/src/index.ts +2 -0
- package/src/tokens.ts +4 -0
- package/src/types.ts +48 -7
- package/src/utils/dates.ts +35 -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
|
@@ -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. */
|
|
@@ -315,6 +364,13 @@ declare const minutesIntoDay: (date: Date) => number;
|
|
|
315
364
|
declare const getYearMonths: (date: Date) => Date[];
|
|
316
365
|
//#endregion
|
|
317
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;
|
|
318
374
|
/**
|
|
319
375
|
* Minutes to shift an event, snapping a vertical pixel drag to the nearest
|
|
320
376
|
* `stepMinutes`. Runs on the UI thread inside the drag gesture. Returns 0 for a
|
|
@@ -520,6 +576,75 @@ declare function parseICalendar(ics: string): ICalEvent[];
|
|
|
520
576
|
*/
|
|
521
577
|
declare function toICalendar(events: ICalEvent[], options?: ToICalendarOptions): string;
|
|
522
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
|
|
523
648
|
//#region src/utils/layout.d.ts
|
|
524
649
|
/** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
|
|
525
650
|
type PositionedEvent<T> = {
|
|
@@ -581,6 +706,18 @@ declare function closedHourBands(day: Date, businessHours: BusinessHours | undef
|
|
|
581
706
|
start: number;
|
|
582
707
|
end: number;
|
|
583
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
|
+
}[];
|
|
584
721
|
//#endregion
|
|
585
722
|
//#region src/utils/monthGrid.d.ts
|
|
586
723
|
/** A single day in the grid, with all the state a custom cell needs to render. */
|
|
@@ -644,6 +781,8 @@ declare function weekdayFormatToken(format: WeekdayFormat): string;
|
|
|
644
781
|
interface UseMonthGridOptions extends DateSelectionConstraints {
|
|
645
782
|
/** First day of the week. Sunday = 0 (default) … Saturday = 6. */
|
|
646
783
|
weekStartsOn?: WeekStartsOn;
|
|
784
|
+
/** Weekdays (0=Sunday…6=Saturday) to drop from the grid and header. */
|
|
785
|
+
hiddenDays?: number[];
|
|
647
786
|
/** Weekday header label width. Default `short` ("Mon"). */
|
|
648
787
|
weekdayFormat?: WeekdayFormat;
|
|
649
788
|
/** Always return six week rows for a fixed-height grid. Default false. */
|
|
@@ -711,4 +850,4 @@ declare function zonedTimeToUtc(wallClock: Date, timeZone: string): Date;
|
|
|
711
850
|
*/
|
|
712
851
|
declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
|
|
713
852
|
//#endregion
|
|
714
|
-
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, getYearMonths, 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
|
@@ -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. */
|
|
@@ -315,6 +364,13 @@ declare const minutesIntoDay: (date: Date) => number;
|
|
|
315
364
|
declare const getYearMonths: (date: Date) => Date[];
|
|
316
365
|
//#endregion
|
|
317
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;
|
|
318
374
|
/**
|
|
319
375
|
* Minutes to shift an event, snapping a vertical pixel drag to the nearest
|
|
320
376
|
* `stepMinutes`. Runs on the UI thread inside the drag gesture. Returns 0 for a
|
|
@@ -520,6 +576,75 @@ declare function parseICalendar(ics: string): ICalEvent[];
|
|
|
520
576
|
*/
|
|
521
577
|
declare function toICalendar(events: ICalEvent[], options?: ToICalendarOptions): string;
|
|
522
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
|
|
523
648
|
//#region src/utils/layout.d.ts
|
|
524
649
|
/** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
|
|
525
650
|
type PositionedEvent<T> = {
|
|
@@ -581,6 +706,18 @@ declare function closedHourBands(day: Date, businessHours: BusinessHours | undef
|
|
|
581
706
|
start: number;
|
|
582
707
|
end: number;
|
|
583
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
|
+
}[];
|
|
584
721
|
//#endregion
|
|
585
722
|
//#region src/utils/monthGrid.d.ts
|
|
586
723
|
/** A single day in the grid, with all the state a custom cell needs to render. */
|
|
@@ -644,6 +781,8 @@ declare function weekdayFormatToken(format: WeekdayFormat): string;
|
|
|
644
781
|
interface UseMonthGridOptions extends DateSelectionConstraints {
|
|
645
782
|
/** First day of the week. Sunday = 0 (default) … Saturday = 6. */
|
|
646
783
|
weekStartsOn?: WeekStartsOn;
|
|
784
|
+
/** Weekdays (0=Sunday…6=Saturday) to drop from the grid and header. */
|
|
785
|
+
hiddenDays?: number[];
|
|
647
786
|
/** Weekday header label width. Default `short` ("Mon"). */
|
|
648
787
|
weekdayFormat?: WeekdayFormat;
|
|
649
788
|
/** Always return six week rows for a fixed-height grid. Default false. */
|
|
@@ -711,4 +850,4 @@ declare function zonedTimeToUtc(wallClock: Date, timeZone: string): Date;
|
|
|
711
850
|
*/
|
|
712
851
|
declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
|
|
713
852
|
//#endregion
|
|
714
|
-
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, getYearMonths, 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 };
|