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