@ilamy/calendar 3.2.1 → 3.3.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
@@ -47,6 +47,27 @@ interface CalendarEvent {
47
47
  * @example { meetingType: 'standup', attendees: ['john', 'jane'] }
48
48
  */
49
49
  data?: Record<string, unknown>;
50
+ /**
51
+ * Whether this event can be moved. Beats the calendar's
52
+ * `editable`; `startEditable` beats this one (FullCalendar
53
+ * `event.editable`).
54
+ */
55
+ editable?: boolean;
56
+ /** Whether this event can be moved. Defaults to `editable`. */
57
+ startEditable?: boolean;
58
+ /** Whether this event can be resized by its edges. Defaults to `editable`. */
59
+ durationEditable?: boolean;
60
+ }
61
+ /**
62
+ * A candidate placement for a dragged event, handed to `eventAllow` (the
63
+ * counterpart of FullCalendar's `DateSpanApi` plus the resource).
64
+ */
65
+ interface EventDropInfo {
66
+ start: Dayjs2;
67
+ end: Dayjs2;
68
+ allDay: boolean;
69
+ /** The resource the event would land on, in resource views. */
70
+ resourceId?: string | number;
50
71
  }
51
72
  /**
52
73
  * Supported days of the week for calendar configuration.
@@ -134,6 +155,23 @@ interface PluginMutationResult {
134
155
  added: CalendarEvent[];
135
156
  /** Existing rows to persist via `onEventDelete`. */
136
157
  deleted: CalendarEvent[];
158
+ /**
159
+ * The update as it was stored, when that is less than what was asked: a
160
+ * scope that keeps its own day applies only the time of day of a drop on
161
+ * another day. `delta` and `endDelta` describe these, not the request.
162
+ * Omit it when the update was stored as asked.
163
+ */
164
+ appliedUpdates?: Partial<CalendarEvent>;
165
+ }
166
+ /**
167
+ * How far an update moved an event's start: whole calendar days plus the change
168
+ * in wall-clock time of day.
169
+ */
170
+ interface EventDelta {
171
+ /** Whole calendar days, in the calendar's zone. */
172
+ days: number;
173
+ /** Change in the time of day on the wall clock, in milliseconds. */
174
+ milliseconds: number;
137
175
  }
138
176
  /**
139
177
  * One user action and every stored row it touched, reported once through
@@ -146,7 +184,10 @@ interface PluginMutationResult {
146
184
  interface EventsChange {
147
185
  /** What the user did. */
148
186
  action: "add" | "update" | "delete";
149
- /** The event the user acted on, as it was shown (an occurrence, for a series). */
187
+ /**
188
+ * The event the user acted on, as it was shown before the change (an
189
+ * occurrence, for a series). The changed rows are in `updated`.
190
+ */
150
191
  event: CalendarEvent;
151
192
  /**
152
193
  * The scope chosen in the plugin's scope dialog, when a plugin manages the
@@ -160,6 +201,34 @@ interface EventsChange {
160
201
  updated: CalendarEvent[];
161
202
  /** Removed rows, the same ones passed to `onEventDelete`. */
162
203
  deleted: CalendarEvent[];
204
+ /**
205
+ * For `'update'`: how far the event's start moved (zero when it did not).
206
+ * Undefined for `'add'` and `'delete'`. A timed event that became all-day is
207
+ * measured from the start of its own day.
208
+ */
209
+ delta?: EventDelta;
210
+ /**
211
+ * For `'update'`: how far the event's end moved (zero when it did not),
212
+ * measured the same way as `delta`, from the two ends as they are. A resize
213
+ * from the end edge sets only this one and a resize from the start edge only
214
+ * `delta`. A move sets both to the same amount, except that a timed event
215
+ * moved onto the all-day row has `delta` measured from the start of its day,
216
+ * so the two can differ. Undefined for `'add'` and `'delete'`.
217
+ *
218
+ * FullCalendar reports a resize through its own `eventResize` callback with
219
+ * `startDelta` and `endDelta`; ilamy reports every action once, through
220
+ * `onEventsChange` (#309), so `delta` is the `startDelta`.
221
+ */
222
+ endDelta?: EventDelta;
223
+ /**
224
+ * Undoes the whole action in the calendar's own store: removes `added`,
225
+ * restores the previous version of every row in `updated`, and puts back
226
+ * `deleted`. A later edit of one of those rows is overwritten; rows other
227
+ * actions added or changed since are kept. It fires no callbacks, and
228
+ * calling it again does nothing. A consumer that controls `events` reverts
229
+ * its own state instead.
230
+ */
231
+ revert: () => void;
163
232
  }
164
233
  /**
165
234
  * Calendar configuration handed to a view's `columns()`/`renderHeader()`.
@@ -169,12 +238,23 @@ interface EventsChange {
169
238
  */
170
239
  interface ViewConfig {
171
240
  firstDayOfWeek: number;
241
+ /** Weekdays (0 = Sunday) the view does not draw. Absent when none are hidden. */
172
242
  hiddenDays?: Set<number>;
173
243
  businessHours?: BusinessHours | BusinessHours[];
174
244
  hideNonBusinessHours?: boolean;
245
+ /** First visible time in hour grids, `'HH:mm'`. Unset shows from midnight. */
246
+ slotMinTime?: string;
247
+ /** End of the visible time in hour grids, exclusive, `'HH:mm'` up to `'24:00'`. */
248
+ slotMaxTime?: string;
175
249
  /** The resource axis. Set only when the calendar renders resources. */
176
250
  resources?: Resource[];
177
251
  /**
252
+ * Whether the calendar is a resource calendar: it has resources, or is still
253
+ * loading them (then `resources` is empty or absent). When absent, it is
254
+ * derived from `resources` being non-empty.
255
+ */
256
+ hasResourceAxis?: boolean;
257
+ /**
178
258
  * The calendar-level resource arrangement (the user's choice): where the
179
259
  * resource axis goes. Only meaningful when `resources` is set.
180
260
  */
@@ -226,6 +306,11 @@ interface HorizontalRowSpec {
226
306
  columns?: HorizontalCellSpec[];
227
307
  className?: string;
228
308
  showDayNumber?: boolean;
309
+ /**
310
+ * Marks the row as one calendar week, so it shows its week number at its
311
+ * start when the calendar's `weekNumbers` is `true`.
312
+ */
313
+ showWeekNumber?: boolean;
229
314
  /** Resource-axis identity when the row belongs to one resource. */
230
315
  resource?: Resource;
231
316
  }
@@ -421,6 +506,15 @@ declare const defaultTranslations: {
421
506
  endDate: string;
422
507
  startTime: string;
423
508
  searchTime: string;
509
+ selectTime: string;
510
+ noTimeFound: string;
511
+ pickDate: string;
512
+ previousMonth: string;
513
+ nextMonth: string;
514
+ previousYear: string;
515
+ nextYear: string;
516
+ previousYears: string;
517
+ nextYears: string;
424
518
  endTime: string;
425
519
  color: string;
426
520
  createEvent: string;
@@ -508,8 +602,9 @@ interface EventFormProps {
508
602
  onDelete?: (event: CalendarEvent) => void;
509
603
  onClose: () => void;
510
604
  }
605
+ import React4 from "react";
606
+ import { ReactNode as ReactNode6, Ref } from "react";
511
607
  import React3 from "react";
512
- import { ReactNode as ReactNode4 } from "react";
513
608
  /**
514
609
  * Available calendar view types. The built-in views (day, week, month, year)
515
610
  * are `PluginView` specs in `features/calendar/components/views`; plugins may
@@ -521,11 +616,103 @@ type CalendarView = string;
521
616
  */
522
617
  type TimeFormat = "12-hour" | "24-hour";
523
618
  /**
619
+ * The public calendar API surface exposed by useIlamyCalendarContext() — for consumers and plugin
620
+ * components. The full internal context is intentionally not exported.
621
+ */
622
+ interface IlamyCalendarApi {
623
+ readonly currentDate: Dayjs3;
624
+ /** The active view's current visible date range (what is on screen). */
625
+ readonly currentRange: DateRange;
626
+ readonly view: CalendarView;
627
+ readonly events: CalendarEvent[];
628
+ readonly rawEvents: CalendarEvent[];
629
+ /**
630
+ * Fetches the visible range again through the `events` function, whatever
631
+ * `lazyFetching` says. The events shown stay until the new ones arrive. Does
632
+ * nothing when `events` is an array.
633
+ */
634
+ readonly refetchEvents: () => void;
635
+ /**
636
+ * Scrolls the hour grids to a time of day, `'HH:mm'` or `'HH:mm:ss'`, the way
637
+ * the `scrollTime` prop does at the start (the minute lands that far into
638
+ * the hour). Does nothing in a view without an hour axis, such as month.
639
+ */
640
+ readonly scrollToTime: (time: string) => void;
641
+ /**
642
+ * Calls the `resources` function again. The resources shown stay until the
643
+ * new ones arrive. Does nothing when `resources` is an array.
644
+ */
645
+ readonly refetchResources: () => void;
646
+ readonly isEventFormOpen: boolean;
647
+ readonly selectedEvent: CalendarEvent | null;
648
+ readonly selectedDate: Dayjs3 | null;
649
+ readonly firstDayOfWeek: number;
650
+ readonly resources: Resource[];
651
+ /** Whether the calendar lays out a resource axis: it has resources, or is still loading them. */
652
+ readonly hasResourceAxis: boolean;
653
+ /** Axis the views lay out along: 'horizontal' (columns) or 'vertical' (rows). */
654
+ readonly orientation: "horizontal" | "vertical";
655
+ readonly setCurrentDate: (date: Dayjs3) => void;
656
+ readonly selectDate: (date: Dayjs3) => void;
657
+ /** Switch view; pass `date` to move there atomically in the same update. */
658
+ readonly setView: (view: CalendarView, date?: Dayjs3) => void;
659
+ readonly nextPeriod: () => void;
660
+ readonly prevPeriod: () => void;
661
+ readonly today: () => void;
662
+ readonly addEvent: (event: CalendarEvent) => void;
663
+ readonly updateEvent: (eventId: string | number, event: Partial<CalendarEvent>) => void;
664
+ readonly deleteEvent: (eventId: string | number) => void;
665
+ readonly openEventForm: (eventData?: OpenEventFormInput) => void;
666
+ readonly closeEventForm: () => void;
667
+ /**
668
+ * Handle a click on an existing event: runs the consumer's `onEventClick`
669
+ * callback if provided, otherwise opens the event for editing. Lets plugin
670
+ * views (e.g. agenda) handle event clicks identically to the built-in views.
671
+ */
672
+ readonly onEventClick: (event: CalendarEvent) => void;
673
+ /**
674
+ * The consumer's custom current-time-indicator renderer, if provided. Lets
675
+ * plugin views (e.g. agenda) render the indicator consistently with the
676
+ * built-in views via the shared `@ilamy/ui` CurrentTimeIndicator.
677
+ */
678
+ readonly renderCurrentTimeIndicator?: (props: RenderCurrentTimeIndicatorProps) => React3.ReactNode;
679
+ /**
680
+ * Events whose resource membership (`resourceIds`, falling back to
681
+ * `resourceId`) contains the given resource. On a calendar without
682
+ * resources this simply filters by the events' own resource fields.
683
+ */
684
+ readonly getEventsForResource: (resourceId: string | number) => CalendarEvent[];
685
+ readonly businessHours?: BusinessHours | BusinessHours[];
686
+ readonly t: TranslatorFunction;
687
+ readonly timeFormat: TimeFormat;
688
+ readonly timezone?: string;
689
+ readonly currentLocale: string;
690
+ readonly getEventsForDateRange: (start: Dayjs3, end: Dayjs3) => CalendarEvent[];
691
+ readonly applyScopedEdit: (event: CalendarEvent, updates: Partial<CalendarEvent>, scope: unknown) => void;
692
+ readonly applyScopedDelete: (event: CalendarEvent, scope: unknown) => void;
693
+ readonly getEventManager: (event: CalendarEvent) => IlamyPlugin | undefined;
694
+ readonly renderSlot: (slotName: string, context: unknown) => React3.ReactNode[];
695
+ readonly collect: (point: string, context: unknown) => unknown[];
696
+ readonly getViews: () => PluginView[];
697
+ }
698
+ /**
699
+ * Public hook exported for library users.
700
+ * Returns a limited set of commonly used properties and methods.
701
+ */
702
+ declare function useIlamyCalendarContext(): IlamyCalendarApi;
703
+ /**
524
704
  * Granularity of the time grid in minutes for day, week, and resource hour views.
525
- * Quarter-hour increments only. `60` shows one row per hour with no sub-hour lines.
526
- * `30` shows two rows per hour. `15` shows four rows per hour with dashed sub-hour separators.
705
+ * `60` shows one row per hour with no sub-hour lines. `30` shows two rows per
706
+ * hour. `15` shows four rows per hour with dashed sub-hour separators.
527
707
  */
528
708
  type SlotDuration = 15 | 30 | 60;
709
+ /** The finest sizes a drag, a resize or a drag-to-create selection can snap to. */
710
+ type SnapDuration = 15 | 30;
711
+ /**
712
+ * How a week number is counted: the locale's own count (`'local'`) or ISO 8601
713
+ * (`'ISO'`).
714
+ */
715
+ type WeekNumberCalculation = "local" | "ISO";
529
716
  /**
530
717
  * Which slice of an event a `renderEvent` call is drawing.
531
718
  *
@@ -631,11 +818,80 @@ interface RenderCurrentTimeIndicatorProps {
631
818
  /** The current calendar view (e.g. 'day', 'week') */
632
819
  view: CalendarView;
633
820
  }
821
+ /**
822
+ * What the calendar asks an `events` function for: the visible range, in the
823
+ * calendar's time zone. `end` is exclusive (the next midnight after the last
824
+ * visible day), like an event's own `end`. In month view the range is the whole
825
+ * grid, including the leading and trailing days of the neighbouring months.
826
+ */
827
+ interface EventsFetchInfo {
828
+ /** Start of the visible range, inclusive. */
829
+ start: Dayjs3;
830
+ /** End of the visible range, exclusive. */
831
+ end: Dayjs3;
832
+ /** `start` as an ISO string. */
833
+ startStr: string;
834
+ /** `end` as an ISO string. */
835
+ endStr: string;
836
+ /** The `timezone` prop, when one is set. */
837
+ timezone?: string;
838
+ }
839
+ /**
840
+ * Loads the events for a visible range. `options.signal` aborts when a newer
841
+ * request supersedes this one, so a `fetch` can be cancelled by passing it on.
842
+ * A result that arrives after being superseded is ignored either way.
843
+ */
844
+ type EventsFetcher = (info: EventsFetchInfo, options: {
845
+ signal: AbortSignal;
846
+ }) => Promise<IlamyCalendarPropEvent[]>;
847
+ /**
848
+ * Loads the resources. Called with the visible range at mount (and, with
849
+ * `refetchResourcesOnNavigate`, whenever the view leaves the fetched range).
850
+ * `options.signal` aborts when a newer request supersedes this one; a late
851
+ * result is ignored either way.
852
+ */
853
+ type ResourcesFetcher = (info: EventsFetchInfo, options: {
854
+ signal: AbortSignal;
855
+ }) => Promise<Resource[]>;
634
856
  interface IlamyCalendarProps {
635
857
  /**
636
- * Array of events to display in the calendar.
858
+ * Drives the calendar from outside it: `ref.current` is the object
859
+ * `useIlamyCalendarContext()` returns, so a toolbar or sidebar of your own
860
+ * calls `ref.current.nextPeriod()`, `setView('week')`, `scrollToTime('13:30')`
861
+ * and the rest. Read it in event handlers and effects, not while rendering:
862
+ * it is set after the calendar mounts and refreshed after every render.
637
863
  */
638
- events?: IlamyCalendarPropEvent[];
864
+ ref?: Ref<IlamyCalendarApi>;
865
+ /**
866
+ * The events to display: an array, or a function the calendar calls with the
867
+ * visible range to load them on demand (see `EventsFetcher`).
868
+ *
869
+ * With a function, the calendar refetches when the visible range leaves the
870
+ * last fetched one (unless `lazyFetching` is off), when `timezone` changes,
871
+ * and when `refetchEvents()` is called. A new function identity does NOT
872
+ * refetch: an inline function would refetch on every render. Call
873
+ * `refetchEvents()` when your query changes. Edits made in the calendar are
874
+ * applied immediately and reported through the `onEvent*` callbacks; the next
875
+ * fetch replaces them with exactly what your function returns.
876
+ */
877
+ events?: IlamyCalendarPropEvent[] | EventsFetcher;
878
+ /**
879
+ * With an `events` function: fetch only when the visible range is not inside
880
+ * the range last fetched. When `false`, every navigation fetches.
881
+ * @default true
882
+ */
883
+ lazyFetching?: boolean;
884
+ /**
885
+ * With an `events` or `resources` function: called with `true` when a fetch
886
+ * starts and `false` when none is in flight any more, for both together. Fires on those transitions only.
887
+ */
888
+ loading?: (isLoading: boolean) => void;
889
+ /**
890
+ * With an `events` function: called when a fetch fails. The events already
891
+ * shown stay, and the next navigation retries. Without it, the error goes to
892
+ * `console.error`.
893
+ */
894
+ onEventsError?: (error: unknown) => void;
639
895
  /**
640
896
  * The first day of the week to display in the calendar.
641
897
  * Can be 'sunday', 'monday', etc. Defaults to 'sunday'.
@@ -661,7 +917,7 @@ interface IlamyCalendarProps {
661
917
  * and `top: var(--ilamy-sticky-top)`, which each grid publishes to clear
662
918
  * its own sticky column and header.
663
919
  */
664
- renderEvent?: (event: CalendarEvent, segment: EventSegment) => ReactNode4;
920
+ renderEvent?: (event: CalendarEvent, segment: EventSegment) => ReactNode6;
665
921
  /**
666
922
  * Callback when an event is clicked.
667
923
  * Provides the clicked event object.
@@ -750,10 +1006,48 @@ interface IlamyCalendarProps {
750
1006
  disableEventClick?: boolean;
751
1007
  /**
752
1008
  * Whether to disable drag-and-drop functionality for calendar events.
753
- * Useful for read-only views or when drag-and-drop is not needed.
1009
+ * Only sets the `editable` default, so an explicit `eventStartEditable`
1010
+ * still enables moving.
1011
+ * @deprecated Use `editable={false}`. Kept until 4.0.
754
1012
  */
755
1013
  disableDragAndDrop?: boolean;
756
1014
  /**
1015
+ * Whether events can be moved. A per-event `editable` beats it, and
1016
+ * `eventStartEditable` beats it for moving.
1017
+ *
1018
+ * Deliberate deviation: FullCalendar defaults `editable` to `false`
1019
+ * (`options.ts:495`, v7.1.1). Drag is on by default here, so this defaults
1020
+ * to `true` until 4.0, when flipping it can be a breaking change.
1021
+ * @default true
1022
+ */
1023
+ editable?: boolean;
1024
+ /**
1025
+ * Whether events can be moved.
1026
+ * @default editable
1027
+ */
1028
+ eventStartEditable?: boolean;
1029
+ /**
1030
+ * Whether events can be resized by dragging an edge. Resize needs a mouse
1031
+ * or a pen: on touch-only devices events can be moved but not resized until
1032
+ * event selection lands. A per-event `durationEditable` beats it. The end edge always shows a handle when
1033
+ * allowed; the start edge needs `eventResizableFromStart`.
1034
+ * @default editable
1035
+ */
1036
+ eventDurationEditable?: boolean;
1037
+ /**
1038
+ * Also show a resize handle on the start edge of an event.
1039
+ * @default false
1040
+ */
1041
+ eventResizableFromStart?: boolean;
1042
+ /**
1043
+ * Vetoes a candidate placement while an event is dragged or resized. Called when the
1044
+ * hovered placement changes, not on every pointer move; returning `false`
1045
+ * shows the not-allowed cursor and a release there changes nothing.
1046
+ * `draggedEvent` is the event as it was before the drag. It does not apply
1047
+ * to the event form or to drag-to-create (FullCalendar's `selectAllow`).
1048
+ */
1049
+ eventAllow?: (dropInfo: EventDropInfo, draggedEvent: CalendarEvent) => boolean;
1050
+ /**
757
1051
  * Maximum number of events to display in one grid cell: a day in month
758
1052
  * view, an hour in the resource day view.
759
1053
  * Additional events will be hidden and can be viewed via a "more" link.
@@ -788,7 +1082,7 @@ interface IlamyCalendarProps {
788
1082
  * Custom header component to replace the default calendar header.
789
1083
  * Useful for adding custom branding or additional controls.
790
1084
  */
791
- headerComponent?: ReactNode4;
1085
+ headerComponent?: ReactNode6;
792
1086
  /**
793
1087
  * Custom class name for the calendar header.
794
1088
  * Useful for applying custom styles to the header.
@@ -806,7 +1100,7 @@ interface IlamyCalendarProps {
806
1100
  * If provided, it will override the default event form component.
807
1101
  * The function receives EventFormProps and should return a React node.
808
1102
  */
809
- renderEventForm?: (props: EventFormProps) => ReactNode4;
1103
+ renderEventForm?: (props: EventFormProps) => ReactNode6;
810
1104
  /**
811
1105
  * Called when the "+N more" overflow indicator in a month/grid cell is
812
1106
  * clicked, receiving the cell's day and its full list of events.
@@ -821,12 +1115,88 @@ interface IlamyCalendarProps {
821
1115
  */
822
1116
  timeFormat?: TimeFormat;
823
1117
  /**
1118
+ * How the labels in the time gutter are written, as `Intl.DateTimeFormat`
1119
+ * options, formatted with the calendar's `locale` and `timezone`. When the
1120
+ * options carry neither `hour12` nor `hourCycle`, a `timeFormat` you passed
1121
+ * decides; without one, the locale does.
1122
+ * Unset keeps the built-in label. `renderHour` takes precedence.
1123
+ *
1124
+ * Only the `Intl.DateTimeFormatOptions` form is supported: no format
1125
+ * strings, no functions, and none of FullCalendar's extras (`meridiem`,
1126
+ * `omitZeroMinute`). Use `renderHour` for anything else.
1127
+ * (FullCalendar v7 calls this `slotHeaderFormat` too.)
1128
+ */
1129
+ slotHeaderFormat?: Intl.DateTimeFormatOptions;
1130
+ /**
1131
+ * How the time on an event bar is written, as `Intl.DateTimeFormat`
1132
+ * options. Same rules as `slotHeaderFormat`. Setting it shows the time
1133
+ * unless `displayEventTime` is `false`. `renderEvent` takes precedence.
1134
+ */
1135
+ eventTimeFormat?: Intl.DateTimeFormatOptions;
1136
+ /**
1137
+ * Whether the built-in event bar shows the event's time. All-day events
1138
+ * never do. Unset: shown only when `eventTimeFormat` is set, so existing
1139
+ * calendars look as they did. Shown with no `eventTimeFormat`, it reads
1140
+ * like "9:30 AM".
1141
+ *
1142
+ * FullCalendar defaults this to on; flipping it here is a 4.0 candidate.
1143
+ */
1144
+ displayEventTime?: boolean;
1145
+ /**
1146
+ * Whether the time on an event bar runs to the end ("9:30 – 10:30").
1147
+ * Needs the time to be shown. FullCalendar defaults the end on when the
1148
+ * event has one; flipping it here is a 4.0 candidate.
1149
+ * @default false
1150
+ */
1151
+ displayEventEnd?: boolean;
1152
+ /**
1153
+ * How a day header is written, as `Intl.DateTimeFormat` options. When set,
1154
+ * the formatted text is the whole header: `{ weekday: 'long' }` gives
1155
+ * "Wednesday" with no day number, and `{ weekday: 'short', day: 'numeric' }`
1156
+ * gives "Wed 12". Applies to the week, day, month and resource headers
1157
+ * (not the agenda plugin). Unset keeps the weekday over the day number.
1158
+ */
1159
+ dayHeaderFormat?: Intl.DateTimeFormatOptions;
1160
+ /**
1161
+ * How the toolbar title is written, as `Intl.DateTimeFormat` options.
1162
+ * A range (week, custom window) is written with `formatRange`. Unset keeps
1163
+ * the built-in title for each view.
1164
+ */
1165
+ titleFormat?: Intl.DateTimeFormatOptions;
1166
+ /**
824
1167
  * Whether to hide non-business hours in Day and Week views.
825
1168
  * Requires businessHours to be configured.
826
1169
  * @default false
827
1170
  */
828
1171
  hideNonBusinessHours?: boolean;
829
1172
  /**
1173
+ * First visible time in the hour grids (day, week, and the resource hour
1174
+ * views in both orientations), `'HH:mm'` or `'HH:mm:ss'`. A bound that falls
1175
+ * inside an hour shows that whole hour. Month, year, agenda and
1176
+ * `weekViewGranularity: 'daily'` ignore it.
1177
+ *
1178
+ * An event outside the range is not drawn; one that crosses its edge is
1179
+ * clipped to it and keeps its real start and end times. Combined with
1180
+ * `hideNonBusinessHours`, the grid shows the overlap of the two ranges.
1181
+ *
1182
+ * Between `'00:00'` and `'24:00'` only. An invalid value, or a range whose
1183
+ * end is not after its start, shows the whole day and logs one
1184
+ * `console.warn` naming the prop.
1185
+ *
1186
+ * @default '00:00'
1187
+ * @example slotMinTime="08:00"
1188
+ */
1189
+ slotMinTime?: string;
1190
+ /**
1191
+ * End of the visible time in the hour grids, exclusive: `'18:00'` shows the
1192
+ * 5 PM row and stops there. `'HH:mm'` or `'HH:mm:ss'` up to `'24:00'`. See
1193
+ * `slotMinTime`.
1194
+ *
1195
+ * @default '24:00'
1196
+ * @example slotMaxTime="18:00"
1197
+ */
1198
+ slotMaxTime?: string;
1199
+ /**
830
1200
  * Whether to hide the iCalendar button in the calendar header.
831
1201
  * Applies to both desktop and mobile header layouts.
832
1202
  * @default false
@@ -875,35 +1245,44 @@ interface IlamyCalendarProps {
875
1245
  * }}
876
1246
  * ```
877
1247
  */
878
- renderCurrentTimeIndicator?: (props: RenderCurrentTimeIndicatorProps) => ReactNode4;
1248
+ renderCurrentTimeIndicator?: (props: RenderCurrentTimeIndicatorProps) => ReactNode6;
879
1249
  /**
880
- * Days of the week to hide from the week view.
881
- * Hidden days won't render as columns, giving remaining days more space.
1250
+ * Days of the week to hide. A hidden day gets no column or row, so the
1251
+ * remaining days share the space.
882
1252
  *
883
- * Applies to:
884
- * - Regular vertical week view (always)
885
- * - Resource vertical week view in hourly granularity
1253
+ * Applies to the month, week and day views, with or without `resources`, in
1254
+ * every orientation and granularity. The day view skips hidden days when you
1255
+ * step to the previous or next day, and opens on the next visible day if it
1256
+ * is given a hidden one.
886
1257
  *
887
- * Does NOT apply to:
888
- * - Resource horizontal week view (layout is days-as-rows)
889
- * - Resource vertical week view in daily granularity
890
- * (`weekViewGranularity: 'daily'`) — non-contiguous visible days would
891
- * break multi-day event positioning
892
- * - Month, day, and year views
1258
+ * An event that runs across a hidden day is drawn as one bar over the visible
1259
+ * days it covers; one that starts or ends on a hidden day is clamped to the
1260
+ * nearest visible day (`EventSegment.isStart` / `isEnd` are false there), and
1261
+ * one that lies wholly on hidden days is not drawn.
1262
+ *
1263
+ * Does NOT apply to the year view, which shows every day of each month, or to
1264
+ * the agenda plugin, which lists events rather than days.
1265
+ *
1266
+ * Hiding all seven days is ignored, with a warning in development.
893
1267
  *
894
1268
  * @default []
895
1269
  * @example ['saturday', 'sunday'] // Hide weekends
896
1270
  */
897
1271
  hiddenDays?: WeekDays[];
898
1272
  /**
1273
+ * Whether to show Saturday and Sunday. `false` is the same as adding both
1274
+ * to `hiddenDays`, and is added to it when both are set.
1275
+ *
1276
+ * @default true
1277
+ */
1278
+ weekends?: boolean;
1279
+ /**
899
1280
  * Custom render function for the hour labels in the gutter/header.
900
1281
  * Receives a Dayjs object for the hour and should return a React node.
901
1282
  */
902
- renderHour?: (date: Dayjs3) => ReactNode4;
1283
+ renderHour?: (date: Dayjs3) => ReactNode6;
903
1284
  /**
904
1285
  * Granularity of the time grid in minutes for day, week, and resource hour views.
905
- * Quarter-hour increments only: `15`, `30`, or `60`.
906
- *
907
1286
  * - `60` (default): one row per hour, no sub-hour lines.
908
1287
  * - `30`: two rows per hour (top of hour, half hour).
909
1288
  * - `15`: four rows per hour with dashed sub-hour separators.
@@ -912,11 +1291,21 @@ interface IlamyCalendarProps {
912
1291
  */
913
1292
  slotDuration?: SlotDuration;
914
1293
  /**
1294
+ * The size, in minutes, a dragged or resized event (and a drag-to-create
1295
+ * selection) snaps to: `15` or `30`. Takes effect only where it is finer than
1296
+ * the cell under the pointer (`slotDuration` in the vertical time grid, one
1297
+ * hour in the horizontal resource timeline) and divides it: with
1298
+ * `slotDuration={60}` and `snapDuration={15}` an event dropped halfway down an
1299
+ * hour row lands on `:30`. Otherwise the cell's own size is used.
1300
+ */
1301
+ snapDuration?: SnapDuration;
1302
+ /**
915
1303
  * Initial scroll position for hour-resolution views (day, week, resource
916
1304
  * day, resource week, in both orientations). Accepts `"HH:mm"` or
917
- * `"HH:mm:ss"`. Minutes are floored to the hour. The scroll target is
918
- * clamped to the nearest visible row when `hideNonBusinessHours` hides
919
- * the requested hour.
1305
+ * `"HH:mm:ss"`. The grid scrolls to the exact minute: `"08:30"` lands
1306
+ * halfway into the 08:00 row. The scroll target is clamped to the nearest
1307
+ * visible row (landing on its edge) when `hideNonBusinessHours` hides the
1308
+ * requested hour.
920
1309
  *
921
1310
  * Reapplied whenever the visible date range changes (navigation, view
922
1311
  * switch), the rendered hours change, or `scrollTime` itself changes, as
@@ -943,8 +1332,8 @@ interface IlamyCalendarProps {
943
1332
  scrollTime?: string;
944
1333
  /**
945
1334
  * Open every scrolling grid on the current moment rather than its start:
946
- * the current hour in time grids (day, week, resource day, hourly resource
947
- * week), and today's column or row in day grids (resource month, daily
1335
+ * the current moment in time grids (day, week, resource day, hourly
1336
+ * resource week), down to the minute, and today's column or row in day grids (resource month, daily
948
1337
  * resource week, #285). Month and year grids do not scroll, so it does
949
1338
  * nothing there.
950
1339
  *
@@ -968,20 +1357,81 @@ interface IlamyCalendarProps {
968
1357
  */
969
1358
  scrollToNow?: boolean;
970
1359
  /**
1360
+ * Whether day, week and resource time grids draw the all-day row above the
1361
+ * hours. When `false` the row is removed and all-day events are not shown in
1362
+ * those views. Month, year and agenda views are unaffected.
1363
+ *
1364
+ * @default true
1365
+ */
1366
+ allDaySlot?: boolean;
1367
+ /**
1368
+ * Whether time grids draw a line at the current time.
1369
+ *
1370
+ * @default true
1371
+ */
1372
+ nowIndicator?: boolean;
1373
+ /**
1374
+ * Whether week numbers are shown.
1375
+ *
1376
+ * - unset (default): the week number appears in the corner of the week and
1377
+ * resource week headers, and month view shows none.
1378
+ * - `true`: additionally shows a number in each row of the month view,
1379
+ * counted from the row's first day.
1380
+ * - `false`: shows week numbers nowhere.
1381
+ */
1382
+ weekNumbers?: boolean;
1383
+ /**
1384
+ * How week numbers are counted.
1385
+ *
1386
+ * - `'local'` (default): the locale's own count.
1387
+ * - `'ISO'`: ISO 8601, week 1 being the week holding the year's first
1388
+ * Thursday. It only changes the number: it does not make weeks start on
1389
+ * Monday. Use `firstDayOfWeek` for that.
1390
+ *
1391
+ * @default 'local'
1392
+ */
1393
+ weekNumberCalculation?: WeekNumberCalculation;
1394
+ /**
971
1395
  * Optional plugins that add behavior/UI (e.g. recurrence). The core ships
972
1396
  * with no plugins by default — pass `recurrencePlugin()` to enable recurring
973
1397
  * events.
974
1398
  */
975
1399
  plugins?: IlamyPlugin[];
976
1400
  /**
977
- * Resources (people, rooms, equipment) to display as a resource axis.
1401
+ * Resources (people, rooms, equipment) to display as a resource axis: an
1402
+ * array, or a function that loads them (see `ResourcesFetcher`).
1403
+ *
1404
+ * A function is called once on mount and again on `refetchResources()`, or
1405
+ * on navigation with `refetchResourcesOnNavigate`. A new function identity
1406
+ * does NOT refetch. Until it resolves the calendar is a resource calendar with no lanes yet;
1407
+ * a failure keeps the resources shown and goes to `onResourcesError`.
978
1408
  * When set: events are shown per matching resource (`resourceIds`, falling
979
1409
  * back to `resourceId`); events with no resource assignment are hidden; the
980
1410
  * year view is hidden from the view switcher.
981
1411
  */
982
- resources?: Resource[];
1412
+ resources?: Resource[] | ResourcesFetcher;
1413
+ /**
1414
+ * With a `resources` function: also fetch when the visible range leaves the
1415
+ * range last fetched, so the function can return resources for the dates in view.
1416
+ * @default false
1417
+ */
1418
+ refetchResourcesOnNavigate?: boolean;
1419
+ /**
1420
+ * Called with the resource list once it is set and after every change: an
1421
+ * array prop whose resources changed, or a fetch result. Compared by
1422
+ * content, so an inline array does not re-fire on every render (`data` is
1423
+ * compared one level deep: same keys, each value `===`; keep objects nested
1424
+ * deeper inside `data` stable). Not called
1425
+ * while there is no list yet.
1426
+ */
1427
+ resourcesSet?: (resources: Resource[]) => void;
1428
+ /**
1429
+ * With a `resources` function: called when a fetch fails. The resources
1430
+ * already shown stay. Without it, the error goes to `console.error`.
1431
+ */
1432
+ onResourcesError?: (error: unknown) => void;
983
1433
  /** Custom render function for resource header cells. */
984
- renderResource?: (resource: Resource) => ReactNode4;
1434
+ renderResource?: (resource: Resource) => ReactNode6;
985
1435
  /**
986
1436
  * How resources are arranged. Only applies when `resources` is set.
987
1437
  * - "horizontal": resources are rows, time is columns (default)
@@ -991,13 +1441,12 @@ interface IlamyCalendarProps {
991
1441
  /**
992
1442
  * Granularity of week-view time slots when `resources` is set.
993
1443
  * - "hourly": one column per hour (default)
994
- * - "daily": one column per day. Note: `hiddenDays` is ignored in daily
995
- * mode (non-contiguous days would break multi-day event positioning).
1444
+ * - "daily": one column per day
996
1445
  */
997
1446
  weekViewGranularity?: "hourly" | "daily";
998
1447
  }
999
- declare const IlamyCalendar: React3.FC<IlamyCalendarProps>;
1000
- import React4 from "react";
1448
+ declare const IlamyCalendar: React4.FC<IlamyCalendarProps>;
1449
+ import React5 from "react";
1001
1450
  /**
1002
1451
  * @deprecated Since v2.0 `IlamyCalendar` accepts `resources`, `renderResource`,
1003
1452
  * `orientation`, and `weekViewGranularity` directly — use it instead. This
@@ -1005,72 +1454,5 @@ import React4 from "react";
1005
1454
  */
1006
1455
  type IlamyResourceCalendarProps = IlamyCalendarProps;
1007
1456
  /** @deprecated Since v2.0 — use `IlamyCalendar` with the `resources` prop. */
1008
- declare const IlamyResourceCalendar: React4.FC<IlamyResourceCalendarProps>;
1009
- import React5 from "react";
1010
- /**
1011
- * The public calendar API surface exposed by useIlamyCalendarContext() — for consumers and plugin
1012
- * components. The full internal context is intentionally not exported.
1013
- */
1014
- interface IlamyCalendarApi {
1015
- readonly currentDate: Dayjs3;
1016
- /** The active view's current visible date range (what is on screen). */
1017
- readonly currentRange: DateRange;
1018
- readonly view: CalendarView;
1019
- readonly events: CalendarEvent[];
1020
- readonly rawEvents: CalendarEvent[];
1021
- readonly isEventFormOpen: boolean;
1022
- readonly selectedEvent: CalendarEvent | null;
1023
- readonly selectedDate: Dayjs3 | null;
1024
- readonly firstDayOfWeek: number;
1025
- readonly resources: Resource[];
1026
- /** Axis the views lay out along: 'horizontal' (columns) or 'vertical' (rows). */
1027
- readonly orientation: "horizontal" | "vertical";
1028
- readonly setCurrentDate: (date: Dayjs3) => void;
1029
- readonly selectDate: (date: Dayjs3) => void;
1030
- /** Switch view; pass `date` to move there atomically in the same update. */
1031
- readonly setView: (view: CalendarView, date?: Dayjs3) => void;
1032
- readonly nextPeriod: () => void;
1033
- readonly prevPeriod: () => void;
1034
- readonly today: () => void;
1035
- readonly addEvent: (event: CalendarEvent) => void;
1036
- readonly updateEvent: (eventId: string | number, event: Partial<CalendarEvent>) => void;
1037
- readonly deleteEvent: (eventId: string | number) => void;
1038
- readonly openEventForm: (eventData?: OpenEventFormInput) => void;
1039
- readonly closeEventForm: () => void;
1040
- /**
1041
- * Handle a click on an existing event: runs the consumer's `onEventClick`
1042
- * callback if provided, otherwise opens the event for editing. Lets plugin
1043
- * views (e.g. agenda) handle event clicks identically to the built-in views.
1044
- */
1045
- readonly onEventClick: (event: CalendarEvent) => void;
1046
- /**
1047
- * The consumer's custom current-time-indicator renderer, if provided. Lets
1048
- * plugin views (e.g. agenda) render the indicator consistently with the
1049
- * built-in views via the shared `@ilamy/ui` CurrentTimeIndicator.
1050
- */
1051
- readonly renderCurrentTimeIndicator?: (props: RenderCurrentTimeIndicatorProps) => React5.ReactNode;
1052
- /**
1053
- * Events whose resource membership (`resourceIds`, falling back to
1054
- * `resourceId`) contains the given resource. On a calendar without
1055
- * resources this simply filters by the events' own resource fields.
1056
- */
1057
- readonly getEventsForResource: (resourceId: string | number) => CalendarEvent[];
1058
- readonly businessHours?: BusinessHours | BusinessHours[];
1059
- readonly t: TranslatorFunction;
1060
- readonly timeFormat: TimeFormat;
1061
- readonly timezone?: string;
1062
- readonly currentLocale: string;
1063
- readonly getEventsForDateRange: (start: Dayjs3, end: Dayjs3) => CalendarEvent[];
1064
- readonly applyScopedEdit: (event: CalendarEvent, updates: Partial<CalendarEvent>, scope: unknown) => void;
1065
- readonly applyScopedDelete: (event: CalendarEvent, scope: unknown) => void;
1066
- readonly getEventManager: (event: CalendarEvent) => IlamyPlugin | undefined;
1067
- readonly renderSlot: (slotName: string, context: unknown) => React5.ReactNode[];
1068
- readonly collect: (point: string, context: unknown) => unknown[];
1069
- readonly getViews: () => PluginView[];
1070
- }
1071
- /**
1072
- * Public hook exported for library users.
1073
- * Returns a limited set of commonly used properties and methods.
1074
- */
1075
- declare function useIlamyCalendarContext(): IlamyCalendarApi;
1076
- export { BusinessHours, CalendarClassesOverride, CalendarEvent, CalendarView, CellInfo, ColumnSpec, Dayjs3 as Dayjs, EventFormProps, EventFormSlotContext, EventMutationScopeSlotContext, EventSegment, EventsChange, HorizontalCellSpec, HorizontalRowSpec, IlamyCalendar, IlamyCalendarApi, IlamyCalendarProps, IlamyPlugin, IlamyResourceCalendar, IlamyResourceCalendarProps, ManipulateType3 as ManipulateType, OpenEventFormInput, PluginDateRange, PluginMutationArgs, PluginMutationResult, PluginView, RenderCurrentTimeIndicatorProps, Resource, SLOT_EVENT_FORM, SLOT_EVENT_MUTATION_SCOPE, SlotDuration, TimeFormat, TranslationKey, Translations, TranslatorFunction, VerticalColumnSpec, ViewConfig, ViewHeaderContext, WeekDays, _default as dayjs, defaultTranslations, useIlamyCalendarContext };
1457
+ declare const IlamyResourceCalendar: React5.FC<IlamyResourceCalendarProps>;
1458
+ export { BusinessHours, CalendarClassesOverride, CalendarEvent, CalendarView, CellInfo, ColumnSpec, Dayjs3 as Dayjs, EventDelta, EventDropInfo, EventFormProps, EventFormSlotContext, EventMutationScopeSlotContext, EventSegment, EventsChange, EventsFetchInfo, EventsFetcher, HorizontalCellSpec, HorizontalRowSpec, IlamyCalendar, IlamyCalendarApi, IlamyCalendarProps, IlamyPlugin, IlamyResourceCalendar, IlamyResourceCalendarProps, ManipulateType3 as ManipulateType, OpenEventFormInput, PluginDateRange, PluginMutationArgs, PluginMutationResult, PluginView, RenderCurrentTimeIndicatorProps, Resource, ResourcesFetcher, SLOT_EVENT_FORM, SLOT_EVENT_MUTATION_SCOPE, SlotDuration, SnapDuration, TimeFormat, TranslationKey, Translations, TranslatorFunction, VerticalColumnSpec, ViewConfig, ViewHeaderContext, WeekDays, WeekNumberCalculation, _default as dayjs, defaultTranslations, useIlamyCalendarContext };