@super-calendar/core 2.14.2 → 2.16.0

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