@super-calendar/core 2.6.0 → 2.8.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 CHANGED
@@ -26,6 +26,35 @@ 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
+ * Whether this event can be moved (dragged to a new time/day). Defaults to the
41
+ * grid's `eventStartEditable` (itself `true`). Set `false` to allow only resize.
42
+ * A `draggable: false` event ignores this (it can neither move nor resize).
43
+ */
44
+ startEditable?: boolean;
45
+ /**
46
+ * Whether this event can be resized (its start or end edge dragged). Defaults to
47
+ * the grid's `eventDurationEditable` (itself `true`). Set `false` to allow only
48
+ * move. A `draggable: false` event ignores this (it can neither move nor resize).
49
+ */
50
+ durationEditable?: boolean;
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";
29
58
  /**
30
59
  * Repeat rule. Pass the event to `expandRecurringEvents(events, start, end)` to
31
60
  * materialise its occurrences within a range; the calendar itself doesn't
@@ -75,8 +104,11 @@ interface RecurrenceRule {
75
104
  */
76
105
  months?: number[];
77
106
  /**
78
- * Dates to skip (exceptions). An occurrence whose day matches one of these is
79
- * dropped by `expandRecurringEvents`. Maps to iCal `EXDATE`.
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`.
80
112
  */
81
113
  exdates?: Date[];
82
114
  /**
@@ -97,15 +129,35 @@ type EventKeyExtractor<T = unknown> = (event: CalendarEvent<T>, index: number) =
97
129
  /** Sunday = 0 … Saturday = 6, matching `Date.prototype.getDay()`. */
98
130
  type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
99
131
  /**
100
- * A day's open hours for `businessHours` shading on the time grid: `{ start, end }`
101
- * in hours (fractions allowed, e.g. 9.5), or `null` when the day is closed (fully
102
- * shaded). `undefined` from the callback means "no business-hours shading". Shared
103
- * by both renderers; pair with `closedHourBands` to get the spans to shade.
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.
104
136
  */
105
- type BusinessHours = (date: Date) => {
137
+ type BusinessHoursValue = {
106
138
  start: number;
107
139
  end: number;
108
- } | null;
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
+ }
109
161
  //#endregion
110
162
  //#region src/tokens.d.ts
111
163
  /** The shared colour palette both renderers derive their themes from. */
@@ -142,6 +194,8 @@ interface CalendarColors {
142
194
  eventBackground: string;
143
195
  /** Default event chip text. */
144
196
  eventText: string;
197
+ /** Shaded band behind a `display: "background"` event. */
198
+ backgroundEvent: string;
145
199
  }
146
200
  /** The default light-theme colour palette. */
147
201
  declare const lightColors: CalendarColors;
@@ -293,16 +347,23 @@ declare const weekDaysCount: (weekStartsOn: WeekStartsOn, weekEndsOn: WeekStarts
293
347
  * from `weekStartsOn` to `weekEndsOn` (anchored to `date`'s week, paging by week);
294
348
  * otherwise every mode shows `viewDayCount` consecutive days starting at `date`.
295
349
  */
296
- declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn) => Date[];
350
+ declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn, hiddenDays?: number[]) => Date[];
297
351
  /**
298
352
  * The calendar weeks covering `month`, padded to whole weeks starting on
299
353
  * `weekStartsOn`. `showSixWeeks` always returns six rows (42 days) for a
300
354
  * fixed-height grid; `isRTL` reverses each week's day order.
301
355
  */
302
- declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, { showSixWeeks, isRTL }?: {
356
+ declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, { showSixWeeks, isRTL, hiddenDays }?: {
303
357
  showSixWeeks?: boolean;
304
358
  isRTL?: boolean;
359
+ hiddenDays?: number[];
305
360
  }) => Date[][];
361
+ /**
362
+ * Drop the days whose weekday (0=Sunday…6=Saturday) is listed in `hiddenDays`.
363
+ * Hiding all seven weekdays is treated as hiding nothing (matching
364
+ * `getViewDays`), so a misconfiguration degrades to the full grid, not a blank.
365
+ */
366
+ declare const filterHiddenDays: (days: Date[], hiddenDays?: number[]) => Date[];
306
367
  /** True when `date` is a Saturday or Sunday. */
307
368
  declare const isWeekend: (date: Date) => boolean;
308
369
  /** True when `date` falls on the current calendar day. */
@@ -315,6 +376,25 @@ declare const minutesIntoDay: (date: Date) => number;
315
376
  declare const getYearMonths: (date: Date) => Date[];
316
377
  //#endregion
317
378
  //#region src/utils/drag.d.ts
379
+ /**
380
+ * True when two time ranges overlap. Edges touching (one ends exactly when the
381
+ * next begins) do not count as an overlap. Compares absolute instants, so events
382
+ * at the same wall-clock time on different days do not overlap.
383
+ */
384
+ declare function eventsOverlap(aStart: Date, aEnd: Date, bStart: Date, bEnd: Date): boolean;
385
+ /**
386
+ * True when the range `[start, end)` would overlap any event in `events` other
387
+ * than `moved` (compared by reference). Used by the `eventOverlap` guard to reject
388
+ * a drag/resize that would land an event on top of another.
389
+ */
390
+ declare function overlapsOtherEvents<T>(events: readonly CalendarEvent<T>[], moved: CalendarEvent<T>, start: Date, end: Date): boolean;
391
+ /**
392
+ * How many calendar days one time-grid page spans, used to advance the view by a
393
+ * whole page (e.g. when dragging an event past the edge into the next week).
394
+ * Deliberately ignores `hiddenDays` so a week always steps 7, matching the
395
+ * keyboard PageUp/PageDown paging and `Calendar`'s own page step.
396
+ */
397
+ declare function pageStepDays(mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number): number;
318
398
  /**
319
399
  * Minutes to shift an event, snapping a vertical pixel drag to the nearest
320
400
  * `stepMinutes`. Runs on the UI thread inside the drag gesture. Returns 0 for a
@@ -520,6 +600,75 @@ declare function parseICalendar(ics: string): ICalEvent[];
520
600
  */
521
601
  declare function toICalendar(events: ICalEvent[], options?: ToICalendarOptions): string;
522
602
  //#endregion
603
+ //#region src/utils/useNow.d.ts
604
+ /** Options for {@link useNow}. */
605
+ interface UseNowOptions {
606
+ /**
607
+ * A fixed instant to use instead of the device clock (a server-synced clock,
608
+ * or a stable value for tests). A fixed instant doesn't tick.
609
+ */
610
+ now?: Date;
611
+ /**
612
+ * Shift the instant into this IANA time zone's wall-clock (the same shift
613
+ * `eventsInTimeZone` applies), so the now indicator lines up with events
614
+ * displayed in that zone rather than the device's.
615
+ */
616
+ timeZone?: string;
617
+ /** Tick interval in ms (default one minute). */
618
+ tickMs?: number;
619
+ }
620
+ /**
621
+ * The current wall-clock time, re-read every `tickMs` while `enabled`, shifted
622
+ * into `timeZone` when given, or pinned to a fixed `now` override. Drives the
623
+ * now indicator on both renderers so it can't disagree with zone-shifted events.
624
+ */
625
+ declare function useNow(enabled: boolean, { now, timeZone, tickMs }?: UseNowOptions): Date;
626
+ //#endregion
627
+ //#region src/utils/useEventSource.d.ts
628
+ /** Options for {@link useEventSource}. */
629
+ interface EventSourceOptions<T> {
630
+ /**
631
+ * Feed format for URL sources: `"json"` (default) expects an array of event
632
+ * objects with ISO `start`/`end` strings; `"ics"` parses an iCalendar feed.
633
+ * URLs ending in `.ics` default to `"ics"`.
634
+ */
635
+ format?: "json" | "ics";
636
+ /**
637
+ * Map the parsed JSON array into events, for feeds whose shape doesn't match
638
+ * `CalendarEvent` (rename fields, attach `resourceId`, filter). The default
639
+ * revives `start`/`end` ISO strings on each item.
640
+ */
641
+ map?: (items: unknown[]) => CalendarEvent<T>[];
642
+ /** Re-fetch every N ms (a live feed). Omit to fetch once. */
643
+ refetchIntervalMs?: number;
644
+ }
645
+ /** What {@link useEventSource} returns. */
646
+ interface EventSourceState<T> {
647
+ /** The fetched events; the previous batch is kept while a refetch runs or fails. */
648
+ events: CalendarEvent<T>[];
649
+ /** True while the first fetch (or a manual refetch) is in flight. */
650
+ loading: boolean;
651
+ /** The last fetch error, or null. Events keep their previous value on error. */
652
+ error: Error | null;
653
+ /** Fetch the source again now. */
654
+ refetch: () => Promise<void>;
655
+ }
656
+ /**
657
+ * Load events from a refreshable source: a JSON feed URL, an iCalendar feed
658
+ * URL, or your own async function. The hook owns fetching, optional interval
659
+ * refetching, and loading/error state; hand the returned `events` to any view.
660
+ *
661
+ * @example
662
+ * ```tsx
663
+ * const { events, loading, refetch } = useEventSource(
664
+ * "https://example.com/feed.ics",
665
+ * { refetchIntervalMs: 5 * 60_000 },
666
+ * );
667
+ * <Calendar mode="week" date={date} events={events} onChangeDate={setDate} />;
668
+ * ```
669
+ */
670
+ declare function useEventSource<T = unknown>(source: string | (() => Promise<CalendarEvent<T>[]>), { format, map, refetchIntervalMs }?: EventSourceOptions<T>): EventSourceState<T>;
671
+ //#endregion
523
672
  //#region src/utils/layout.d.ts
524
673
  /** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
525
674
  type PositionedEvent<T> = {
@@ -581,8 +730,62 @@ declare function closedHourBands(day: Date, businessHours: BusinessHours | undef
581
730
  start: number;
582
731
  end: number;
583
732
  }[];
733
+ /** True when the event paints as a shaded background band, not an event box. */
734
+ declare function isBackgroundEvent<T>(event: CalendarEvent<T>): boolean;
735
+ /**
736
+ * The background events of `events` sliced to `day`, as fractional-hour bands
737
+ * (an all-day or multi-day background covers the day's full window). Shared by
738
+ * both renderers so the shading can't disagree.
739
+ */
740
+ declare function backgroundBandsForDay<T>(events: CalendarEvent<T>[], day: Date): {
741
+ event: CalendarEvent<T>;
742
+ startHours: number;
743
+ endHours: number;
744
+ }[];
584
745
  //#endregion
585
746
  //#region src/utils/monthGrid.d.ts
747
+ /**
748
+ * One event's placement within a single week row of the month grid: the column
749
+ * span it covers and the lane (stacked row) it sits in, plus whether it continues
750
+ * past this row's edges (so the renderer can draw a "continues" affordance and
751
+ * square off the clipped end). Columns index into the row's `days` array, so with
752
+ * `hiddenDays` a bar spans the visible columns it touches.
753
+ */
754
+ interface MonthEventSegment<T = unknown> {
755
+ event: CalendarEvent<T>;
756
+ /** First covered column in the row (0-based, inclusive). */
757
+ startCol: number;
758
+ /** Last covered column in the row (inclusive). */
759
+ endCol: number;
760
+ /** Stacking row within the day cells; 0 is the topmost. */
761
+ lane: number;
762
+ /** The event started before this row's first day. */
763
+ continuesBefore: boolean;
764
+ /** The event ends after this row's last day. */
765
+ continuesAfter: boolean;
766
+ }
767
+ /** The laid-out event segments for one week row, with the number of lanes used. */
768
+ interface MonthWeekEvents<T = unknown> {
769
+ segments: MonthEventSegment<T>[];
770
+ /** Highest lane index used + 1 (0 when the row has no events). */
771
+ laneCount: number;
772
+ }
773
+ /**
774
+ * Lay out one week row's events as continuous horizontal bars: each event becomes
775
+ * a single segment spanning the columns it covers (not a chip repeated per day),
776
+ * stacked into lanes so overlapping events sit on separate rows. Multi-day events
777
+ * that cross the row edges are marked `continuesBefore`/`continuesAfter`. Shared by
778
+ * both renderers so the month grid draws identical spanning bars.
779
+ *
780
+ * Column indices map into the given `days` array in whatever display order it uses,
781
+ * so this is order-independent: a right-to-left (reversed) week lays out correctly,
782
+ * and `continuesBefore`/`continuesAfter` track the array's first/last column edge
783
+ * (not chronology), so the clipped end is squared on the right visual side.
784
+ *
785
+ * Lanes are packed greedily after sorting by start column then longest span first,
786
+ * matching how calendars keep long events on the upper lanes.
787
+ */
788
+ declare function layoutMonthWeek<T>(days: Date[], events: readonly CalendarEvent<T>[]): MonthWeekEvents<T>;
586
789
  /** A single day in the grid, with all the state a custom cell needs to render. */
587
790
  interface MonthGridDay {
588
791
  /** The day this cell represents. */
@@ -644,6 +847,8 @@ declare function weekdayFormatToken(format: WeekdayFormat): string;
644
847
  interface UseMonthGridOptions extends DateSelectionConstraints {
645
848
  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
646
849
  weekStartsOn?: WeekStartsOn;
850
+ /** Weekdays (0=Sunday…6=Saturday) to drop from the grid and header. */
851
+ hiddenDays?: number[];
647
852
  /** Weekday header label width. Default `short` ("Mon"). */
648
853
  weekdayFormat?: WeekdayFormat;
649
854
  /** Always return six week rows for a fixed-height grid. Default false. */
@@ -711,4 +916,4 @@ declare function zonedTimeToUtc(wallClock: Date, timeZone: string): Date;
711
916
  */
712
917
  declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
713
918
  //#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 };
919
+ 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, MonthEventSegment, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, MonthWeekEvents, 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, eventsOverlap, expandRecurringEvents, filterHiddenDays, formatHour, getIsToday, getViewDays, getWeekDays, getYearMonths, groupEventsByDay, isAllDayEvent, isBackgroundEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, layoutMonthWeek, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, overlapsOtherEvents, 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,35 @@ 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
+ * Whether this event can be moved (dragged to a new time/day). Defaults to the
41
+ * grid's `eventStartEditable` (itself `true`). Set `false` to allow only resize.
42
+ * A `draggable: false` event ignores this (it can neither move nor resize).
43
+ */
44
+ startEditable?: boolean;
45
+ /**
46
+ * Whether this event can be resized (its start or end edge dragged). Defaults to
47
+ * the grid's `eventDurationEditable` (itself `true`). Set `false` to allow only
48
+ * move. A `draggable: false` event ignores this (it can neither move nor resize).
49
+ */
50
+ durationEditable?: boolean;
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";
29
58
  /**
30
59
  * Repeat rule. Pass the event to `expandRecurringEvents(events, start, end)` to
31
60
  * materialise its occurrences within a range; the calendar itself doesn't
@@ -75,8 +104,11 @@ interface RecurrenceRule {
75
104
  */
76
105
  months?: number[];
77
106
  /**
78
- * Dates to skip (exceptions). An occurrence whose day matches one of these is
79
- * dropped by `expandRecurringEvents`. Maps to iCal `EXDATE`.
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`.
80
112
  */
81
113
  exdates?: Date[];
82
114
  /**
@@ -97,15 +129,35 @@ type EventKeyExtractor<T = unknown> = (event: CalendarEvent<T>, index: number) =
97
129
  /** Sunday = 0 … Saturday = 6, matching `Date.prototype.getDay()`. */
98
130
  type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
99
131
  /**
100
- * A day's open hours for `businessHours` shading on the time grid: `{ start, end }`
101
- * in hours (fractions allowed, e.g. 9.5), or `null` when the day is closed (fully
102
- * shaded). `undefined` from the callback means "no business-hours shading". Shared
103
- * by both renderers; pair with `closedHourBands` to get the spans to shade.
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.
104
136
  */
105
- type BusinessHours = (date: Date) => {
137
+ type BusinessHoursValue = {
106
138
  start: number;
107
139
  end: number;
108
- } | null;
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
+ }
109
161
  //#endregion
110
162
  //#region src/tokens.d.ts
111
163
  /** The shared colour palette both renderers derive their themes from. */
@@ -142,6 +194,8 @@ interface CalendarColors {
142
194
  eventBackground: string;
143
195
  /** Default event chip text. */
144
196
  eventText: string;
197
+ /** Shaded band behind a `display: "background"` event. */
198
+ backgroundEvent: string;
145
199
  }
146
200
  /** The default light-theme colour palette. */
147
201
  declare const lightColors: CalendarColors;
@@ -293,16 +347,23 @@ declare const weekDaysCount: (weekStartsOn: WeekStartsOn, weekEndsOn: WeekStarts
293
347
  * from `weekStartsOn` to `weekEndsOn` (anchored to `date`'s week, paging by week);
294
348
  * otherwise every mode shows `viewDayCount` consecutive days starting at `date`.
295
349
  */
296
- declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn) => Date[];
350
+ declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn, hiddenDays?: number[]) => Date[];
297
351
  /**
298
352
  * The calendar weeks covering `month`, padded to whole weeks starting on
299
353
  * `weekStartsOn`. `showSixWeeks` always returns six rows (42 days) for a
300
354
  * fixed-height grid; `isRTL` reverses each week's day order.
301
355
  */
302
- declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, { showSixWeeks, isRTL }?: {
356
+ declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, { showSixWeeks, isRTL, hiddenDays }?: {
303
357
  showSixWeeks?: boolean;
304
358
  isRTL?: boolean;
359
+ hiddenDays?: number[];
305
360
  }) => Date[][];
361
+ /**
362
+ * Drop the days whose weekday (0=Sunday…6=Saturday) is listed in `hiddenDays`.
363
+ * Hiding all seven weekdays is treated as hiding nothing (matching
364
+ * `getViewDays`), so a misconfiguration degrades to the full grid, not a blank.
365
+ */
366
+ declare const filterHiddenDays: (days: Date[], hiddenDays?: number[]) => Date[];
306
367
  /** True when `date` is a Saturday or Sunday. */
307
368
  declare const isWeekend: (date: Date) => boolean;
308
369
  /** True when `date` falls on the current calendar day. */
@@ -315,6 +376,25 @@ declare const minutesIntoDay: (date: Date) => number;
315
376
  declare const getYearMonths: (date: Date) => Date[];
316
377
  //#endregion
317
378
  //#region src/utils/drag.d.ts
379
+ /**
380
+ * True when two time ranges overlap. Edges touching (one ends exactly when the
381
+ * next begins) do not count as an overlap. Compares absolute instants, so events
382
+ * at the same wall-clock time on different days do not overlap.
383
+ */
384
+ declare function eventsOverlap(aStart: Date, aEnd: Date, bStart: Date, bEnd: Date): boolean;
385
+ /**
386
+ * True when the range `[start, end)` would overlap any event in `events` other
387
+ * than `moved` (compared by reference). Used by the `eventOverlap` guard to reject
388
+ * a drag/resize that would land an event on top of another.
389
+ */
390
+ declare function overlapsOtherEvents<T>(events: readonly CalendarEvent<T>[], moved: CalendarEvent<T>, start: Date, end: Date): boolean;
391
+ /**
392
+ * How many calendar days one time-grid page spans, used to advance the view by a
393
+ * whole page (e.g. when dragging an event past the edge into the next week).
394
+ * Deliberately ignores `hiddenDays` so a week always steps 7, matching the
395
+ * keyboard PageUp/PageDown paging and `Calendar`'s own page step.
396
+ */
397
+ declare function pageStepDays(mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number): number;
318
398
  /**
319
399
  * Minutes to shift an event, snapping a vertical pixel drag to the nearest
320
400
  * `stepMinutes`. Runs on the UI thread inside the drag gesture. Returns 0 for a
@@ -520,6 +600,75 @@ declare function parseICalendar(ics: string): ICalEvent[];
520
600
  */
521
601
  declare function toICalendar(events: ICalEvent[], options?: ToICalendarOptions): string;
522
602
  //#endregion
603
+ //#region src/utils/useNow.d.ts
604
+ /** Options for {@link useNow}. */
605
+ interface UseNowOptions {
606
+ /**
607
+ * A fixed instant to use instead of the device clock (a server-synced clock,
608
+ * or a stable value for tests). A fixed instant doesn't tick.
609
+ */
610
+ now?: Date;
611
+ /**
612
+ * Shift the instant into this IANA time zone's wall-clock (the same shift
613
+ * `eventsInTimeZone` applies), so the now indicator lines up with events
614
+ * displayed in that zone rather than the device's.
615
+ */
616
+ timeZone?: string;
617
+ /** Tick interval in ms (default one minute). */
618
+ tickMs?: number;
619
+ }
620
+ /**
621
+ * The current wall-clock time, re-read every `tickMs` while `enabled`, shifted
622
+ * into `timeZone` when given, or pinned to a fixed `now` override. Drives the
623
+ * now indicator on both renderers so it can't disagree with zone-shifted events.
624
+ */
625
+ declare function useNow(enabled: boolean, { now, timeZone, tickMs }?: UseNowOptions): Date;
626
+ //#endregion
627
+ //#region src/utils/useEventSource.d.ts
628
+ /** Options for {@link useEventSource}. */
629
+ interface EventSourceOptions<T> {
630
+ /**
631
+ * Feed format for URL sources: `"json"` (default) expects an array of event
632
+ * objects with ISO `start`/`end` strings; `"ics"` parses an iCalendar feed.
633
+ * URLs ending in `.ics` default to `"ics"`.
634
+ */
635
+ format?: "json" | "ics";
636
+ /**
637
+ * Map the parsed JSON array into events, for feeds whose shape doesn't match
638
+ * `CalendarEvent` (rename fields, attach `resourceId`, filter). The default
639
+ * revives `start`/`end` ISO strings on each item.
640
+ */
641
+ map?: (items: unknown[]) => CalendarEvent<T>[];
642
+ /** Re-fetch every N ms (a live feed). Omit to fetch once. */
643
+ refetchIntervalMs?: number;
644
+ }
645
+ /** What {@link useEventSource} returns. */
646
+ interface EventSourceState<T> {
647
+ /** The fetched events; the previous batch is kept while a refetch runs or fails. */
648
+ events: CalendarEvent<T>[];
649
+ /** True while the first fetch (or a manual refetch) is in flight. */
650
+ loading: boolean;
651
+ /** The last fetch error, or null. Events keep their previous value on error. */
652
+ error: Error | null;
653
+ /** Fetch the source again now. */
654
+ refetch: () => Promise<void>;
655
+ }
656
+ /**
657
+ * Load events from a refreshable source: a JSON feed URL, an iCalendar feed
658
+ * URL, or your own async function. The hook owns fetching, optional interval
659
+ * refetching, and loading/error state; hand the returned `events` to any view.
660
+ *
661
+ * @example
662
+ * ```tsx
663
+ * const { events, loading, refetch } = useEventSource(
664
+ * "https://example.com/feed.ics",
665
+ * { refetchIntervalMs: 5 * 60_000 },
666
+ * );
667
+ * <Calendar mode="week" date={date} events={events} onChangeDate={setDate} />;
668
+ * ```
669
+ */
670
+ declare function useEventSource<T = unknown>(source: string | (() => Promise<CalendarEvent<T>[]>), { format, map, refetchIntervalMs }?: EventSourceOptions<T>): EventSourceState<T>;
671
+ //#endregion
523
672
  //#region src/utils/layout.d.ts
524
673
  /** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
525
674
  type PositionedEvent<T> = {
@@ -581,8 +730,62 @@ declare function closedHourBands(day: Date, businessHours: BusinessHours | undef
581
730
  start: number;
582
731
  end: number;
583
732
  }[];
733
+ /** True when the event paints as a shaded background band, not an event box. */
734
+ declare function isBackgroundEvent<T>(event: CalendarEvent<T>): boolean;
735
+ /**
736
+ * The background events of `events` sliced to `day`, as fractional-hour bands
737
+ * (an all-day or multi-day background covers the day's full window). Shared by
738
+ * both renderers so the shading can't disagree.
739
+ */
740
+ declare function backgroundBandsForDay<T>(events: CalendarEvent<T>[], day: Date): {
741
+ event: CalendarEvent<T>;
742
+ startHours: number;
743
+ endHours: number;
744
+ }[];
584
745
  //#endregion
585
746
  //#region src/utils/monthGrid.d.ts
747
+ /**
748
+ * One event's placement within a single week row of the month grid: the column
749
+ * span it covers and the lane (stacked row) it sits in, plus whether it continues
750
+ * past this row's edges (so the renderer can draw a "continues" affordance and
751
+ * square off the clipped end). Columns index into the row's `days` array, so with
752
+ * `hiddenDays` a bar spans the visible columns it touches.
753
+ */
754
+ interface MonthEventSegment<T = unknown> {
755
+ event: CalendarEvent<T>;
756
+ /** First covered column in the row (0-based, inclusive). */
757
+ startCol: number;
758
+ /** Last covered column in the row (inclusive). */
759
+ endCol: number;
760
+ /** Stacking row within the day cells; 0 is the topmost. */
761
+ lane: number;
762
+ /** The event started before this row's first day. */
763
+ continuesBefore: boolean;
764
+ /** The event ends after this row's last day. */
765
+ continuesAfter: boolean;
766
+ }
767
+ /** The laid-out event segments for one week row, with the number of lanes used. */
768
+ interface MonthWeekEvents<T = unknown> {
769
+ segments: MonthEventSegment<T>[];
770
+ /** Highest lane index used + 1 (0 when the row has no events). */
771
+ laneCount: number;
772
+ }
773
+ /**
774
+ * Lay out one week row's events as continuous horizontal bars: each event becomes
775
+ * a single segment spanning the columns it covers (not a chip repeated per day),
776
+ * stacked into lanes so overlapping events sit on separate rows. Multi-day events
777
+ * that cross the row edges are marked `continuesBefore`/`continuesAfter`. Shared by
778
+ * both renderers so the month grid draws identical spanning bars.
779
+ *
780
+ * Column indices map into the given `days` array in whatever display order it uses,
781
+ * so this is order-independent: a right-to-left (reversed) week lays out correctly,
782
+ * and `continuesBefore`/`continuesAfter` track the array's first/last column edge
783
+ * (not chronology), so the clipped end is squared on the right visual side.
784
+ *
785
+ * Lanes are packed greedily after sorting by start column then longest span first,
786
+ * matching how calendars keep long events on the upper lanes.
787
+ */
788
+ declare function layoutMonthWeek<T>(days: Date[], events: readonly CalendarEvent<T>[]): MonthWeekEvents<T>;
586
789
  /** A single day in the grid, with all the state a custom cell needs to render. */
587
790
  interface MonthGridDay {
588
791
  /** The day this cell represents. */
@@ -644,6 +847,8 @@ declare function weekdayFormatToken(format: WeekdayFormat): string;
644
847
  interface UseMonthGridOptions extends DateSelectionConstraints {
645
848
  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
646
849
  weekStartsOn?: WeekStartsOn;
850
+ /** Weekdays (0=Sunday…6=Saturday) to drop from the grid and header. */
851
+ hiddenDays?: number[];
647
852
  /** Weekday header label width. Default `short` ("Mon"). */
648
853
  weekdayFormat?: WeekdayFormat;
649
854
  /** Always return six week rows for a fixed-height grid. Default false. */
@@ -711,4 +916,4 @@ declare function zonedTimeToUtc(wallClock: Date, timeZone: string): Date;
711
916
  */
712
917
  declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
713
918
  //#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 };
919
+ 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, MonthEventSegment, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, MonthWeekEvents, 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, eventsOverlap, expandRecurringEvents, filterHiddenDays, formatHour, getIsToday, getViewDays, getWeekDays, getYearMonths, groupEventsByDay, isAllDayEvent, isBackgroundEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, layoutMonthWeek, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, overlapsOtherEvents, pageStepDays, parseICalendar, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toICalendar, toZonedTime, useCalendarSelection, useDateRange, useEventSource, useMonthGrid, useNow, viewDayCount, weekDaysCount, weekdayFormatToken, zonedTimeToUtc };