@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 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). An occurrence whose day matches one of these is
79
- * dropped by `expandRecurringEvents`. Maps to iCal `EXDATE`.
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 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.
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 BusinessHours = (date: Date) => {
125
+ type BusinessHoursValue = {
106
126
  start: number;
107
127
  end: number;
108
- } | null;
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). An occurrence whose day matches one of these is
79
- * dropped by `expandRecurringEvents`. Maps to iCal `EXDATE`.
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 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.
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 BusinessHours = (date: Date) => {
125
+ type BusinessHoursValue = {
106
126
  start: number;
107
127
  end: number;
108
- } | null;
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 };